Updated 2026-11-18

VitePress JSON-LD: structured data with transformHead

VitePress writes no structured data, and its default theme adds none. Google recommends JSON-LD for structured data (Google Search Central: structured data). On a docs site that means a TechArticle for each page, a BreadcrumbList that matches the sidebar and a WebSite on the home page. VitePress already has all of that at build time: the transformHead hook gets each page's data, the site title and the theme config, including the sidebar. Tested on VitePress 1.6.

1. Put the builder in its own file

Save this as .vitepress/jsonld.mjs and change site to your domain. It assumes cleanUrls: true (the VitePress SEO guide explains why); without it, add .html to the page URLs that don't end in /.

const site = 'https://docs.example.com'

// '/guide/install' for guide/install.md, '/guide/' for guide/index.md, '/' for index.md
const toLink = (path) =>
  '/' + path.replace(/^\//, '').replace(/(^|\/)index(\.md|\.html)?$/, '$1').replace(/\.(md|html)$/, '')

// The sidebar groups above a page, outermost first, or null if it isn't in the sidebar
function trail(items, link, parents = []) {
  for (const item of items ?? []) {
    if (item.link && toLink(item.link) === link) return parents
    const found = trail(item.items, link, [...parents, item])
    if (found) return found
  }
  return null
}

// A sidebar keyed by path ('/guide/': [...]) uses the longest key the page starts with
function sidebarFor(sidebar, link) {
  if (Array.isArray(sidebar)) return sidebar
  const key = Object.keys(sidebar ?? {})
    .filter((k) => link.startsWith(k))
    .sort((a, b) => b.length - a.length)[0]
  const s = key ? sidebar[key] : []
  return Array.isArray(s) ? s : s.items
}

export function jsonLd({ pageData, siteData, description }) {
  if (pageData.isNotFound) return []
  const link = toLink(pageData.relativePath)
  const url = site + link
  const website = { '@type': 'WebSite', name: siteData.title, url: site + '/' }
  let ld
  if (link === '/') {
    ld = { '@context': 'https://schema.org', ...website, description }
  } else {
    const crumbs = [{ name: siteData.title, item: site + '/' }]
    for (const group of trail(sidebarFor(siteData.themeConfig.sidebar, link), link) ?? []) {
      if (group.link && toLink(group.link) !== link) crumbs.push({ name: group.text, item: site + toLink(group.link) })
    }
    crumbs.push({ name: pageData.title })
    const article = {
      '@type': 'TechArticle',
      headline: pageData.title,
      description,
      url,
      inLanguage: siteData.lang,
      isPartOf: website,
    }
    if (pageData.lastUpdated) article.dateModified = new Date(pageData.lastUpdated).toISOString()
    ld = {
      '@context': 'https://schema.org',
      '@graph': [
        article,
        {
          '@type': 'BreadcrumbList',
          itemListElement: crumbs.map((c, i) => ({ '@type': 'ListItem', position: i + 1, ...c })),
        },
      ],
    }
  }
  // < keeps a "</script>" in a title or description from ending the tag
  return [['script', { type: 'application/ld+json' }, JSON.stringify(ld).replace(/</g, '\\u003c')]]
}

2. Call it from the config

// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import { jsonLd } from './jsonld.mjs'

export default defineConfig({
  title: 'Example Docs',
  description: 'Reference and guides for the Example CLI.',
  lang: 'en-US',
  cleanUrls: true,
  lastUpdated: true,
  themeConfig: {
    sidebar: [
      { text: 'Guide', link: '/guide/', items: [
        { text: 'Install', link: '/guide/install' },
        { text: 'Configure', link: '/guide/configure' },
      ] },
    ],
  },
  transformHead: (ctx) => jsonLd(ctx),
})

If you already have a transformHead for Open Graph tags, return both: return [...ogTags, ...jsonLd(ctx)]. The hook only runs during vitepress build, so look for the markup in .vitepress/dist, not in the dev server.

Notes on what it does:

On guide/install.md the output is (shortened):

<script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"TechArticle","headline":"Install","description":"How to install the CLI & its plugins.","url":"https://docs.example.com/guide/install",…},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Example Docs","item":"https://docs.example.com/"},{"@type":"ListItem","position":2,"name":"Guide","item":"https://docs.example.com/guide/"},{"@type":"ListItem","position":3,"name":"Install"}]}]}</script>

3. Check the build

List built pages with no JSON-LD at all (only 404.html should be left):

npx vitepress build && grep -rL --include='*.html' 'application/ld+json' .vitepress/dist

Then check a few pages from different sidebar sections. The free structured data checker takes a URL or pasted markup and checks each block against the properties Google requires and recommends. Google's Rich Results Test shows how Google reads the breadcrumbs. The free site checker samples pages across a live site and shows which have no structured data, no description or no share image.

Common mistakes

Automating it with Headlark

The hook gives every page the same generic types. Headlark's build step runs after vitepress build and writes what each page is missing from its content: one to three JSON-LD blocks with only properties whose values appear on the page (a how-to, an FAQ, a software application), plus missing descriptions, Open Graph tags and alt text. A type you already emit is kept as it is and never added twice, so it works alongside the code above.

Try it

Try it free for 14 days on one site and up to 500 pages, no card needed. Add your site, copy its secret key, and your next build ships with SEO.