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:
- Escaping.
JSON.stringifywrites valid JSON, and replacing<with\u003ckeeps a<in a title or description from being read as markup inside the tag (VitePress already refuses a raw</script>in front matter). The result is still the same JSON to a parser. Never build the JSON as a string around the title. - Breadcrumbs follow the sidebar, not the URL. A sidebar group only becomes a crumb when it has its own
link, because every item except the last needs a real URL. Groups without one are left out. The last item, the page itself, has noitem, which Google accepts. A sidebar keyed by path ({ '/guide/': [...] }) works too; pages that aren't in any sidebar get a two-item trail. - Descriptions are the
descriptionVitePress already composed for the meta tag: the page's frontmatterdescription, else the site's. dateModifiedcomes fromlastUpdated: true, which VitePress reads from each file's last git commit, so it only changes when the page does. Leave it out rather than using the build date. In CI, fetch the full history (fetch-depth: 0) or every page gets the same date.- The 404 page gets no markup.
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
- Breadcrumb items pointing at groups with no page. A crumb URL that 404s makes the trail invalid.
- Adding the script in
headin the config. Staticheadentries are the same on every page, so every page claims the same headline and URL. - A second
TechArticlefrom a plugin or a theme component. Search the built HTML forld+jsonbefore adding it. - Markup for content that isn't on the page. Authors, ratings and versions must also be visible.
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.