Help Docs

Write your product's help center as Markdown files: sections and groups, the sidebar order, search, and what CI checks.

The help center (/docs) is a folder of Markdown files in your repository, shown with a sidebar, an "On this page" list, breadcrumbs, previous and next links, and a ⌘K search. Each file is a page, rendered once and served from the edge cache like the other marketing pages. It is built on the same engine as the blog and changelog; to read pages from a CMS instead, see Content Sources.

This page is part of the Marketing documentation.

The product help center with its sidebar and table of contents.Click to expand

The product help center with its sidebar and table of contents.

What's Where

PartLocation
Pages and folder orderapps/web/content/docs/**/*.md, meta.json per folder
Collection, frontmatter fieldsapps/web/config/content.config.ts → docs
Pagesapps/web/pages/(marketing)/docs/ (index, [slug], [section]/[slug], [section]/[group]/[slug])
Page compositionDocsPage from @kit/content/ui (packages/content/src/ui/docs-page.tsx); app bindings in apps/web/components/content-ui.tsx
Search indexapps/web/routes/docs/search.json.ts (/docs/search.json)
Labels (sidebar, search, pager)apps/web/messages/<locale>/marketing.json → docs
Engine and page blocks@kit/content (packages/content/)

Add a Page

Create a file; its path is its URL. apps/web/content/docs/billing/refunds.md is served at /docs/billing/refunds:

---
title: Refunds
description: Ask for a refund within 14 days of a charge.
---
## Request a refund
Owners request a refund from **Settings → Billing → Invoices**.

It appears in the sidebar, the search and the previous/next links without any other change. Run pnpm dev and open the URL to see it; commit and deploy to publish.

File and folder names are lowercase words joined by hyphens (cancel-your-subscription.md). The body is Markdown, as on the blog: headings, lists, tables, code blocks and callouts (> [!TIP], ::: warning). Each ## and ### heading becomes an entry in "On this page" and a search result.

Sections and Groups

Docs go three levels deep:

LevelExample fileShown as
Pagecontent/docs/faq.mdA link at the sidebar's top level, among the sections
Sectioncontent/docs/billing/plans.mdA bold heading with its pages under it
Groupcontent/docs/billing/payment-methods/cards.mdA collapsible list inside the section

A folder's index.md is the folder's own page: content/docs/billing/index.md is served at /docs/billing, and content/docs/index.md is the docs home (/docs). A folder without one redirects to its first page, so /docs/billing always works. Don't add both billing.md and billing/index.md: they are the same page, and CI rejects the pair.

Order and Titles

Each folder may have a meta.json, which titles it and orders what's inside:

{
"title": "Billing",
"pages": ["plans", "payment-methods", "invoices"]
}
  • pages lists the folder's pages and subfolders by file name, without .md. They come first, in that order.
  • Anything not listed follows, by its order frontmatter (lowest first), then by title. A new page shows up without editing meta.json.
  • title names the folder in the sidebar. Without it, the folder takes its index.md's title, or its name (payment-methods → "Payment methods").
  • meta.json takes those two keys only.

To place a page without listing it, set order:

---
title: Plans
description: Compare plans and change yours at any time.
order: 1
---

A folder is placed the same way: by its name in the parent's pages, or by the order of its index.md.

Frontmatter

FieldRequiredNotes
titleyesThe page's <h1>, <title>, sidebar link and search result
descriptionyesUnder the title, <meta name="description">, and searched
ordernoA whole number; places the page among those meta.json doesn't list
updatednoISO date (2026-10-30), shown as "Updated October 30, 2026"
statusnopublished (default) or draft
imagenoA path under apps/web/public/, as on the blog

There is no date: docs are ordered by their folders, not by when they were written. The schema is strict, so a misspelled field fails. To add a field, extend the schema in config/content.config.ts (schema: docSchema.extend({ … })); the page gets it typed.

Drafts

Set status: draft to keep a page off the site. Drafts are listed on the dev server only: deployed, they have no page, sidebar link or search result. A folder whose pages are all drafts disappears from the sidebar until one is published.

⌘K (Ctrl K on Windows and Linux), or the search field at the top of the sidebar, opens the search. It finds pages and sections by their title, headings and text, and opens the section at its heading.

The index is /docs/search.json: plain text, one record per page intro and per ##/### section, with code blocks left out and each section's text capped at 500 characters. It is built from published pages only, cached at the edge like the pages, and downloaded by the browser the first time someone searches, together with the search engine (MiniSearch, about 6 KB). Nothing about searching is sent to the server.

Every visitor who searches downloads the whole index. For a large docs collection, measure the actual /docs/search.json response size; unit tests do not approximate Markdown output or impose a fixed size budget.

What CI Checks

pnpm test:unit checks every docs file, drafts included, and fails naming the file and what to fix. Fix them in the order they appear: a frontmatter or slug error stops the tree check, and a meta.json with an unknown key is ignored whole (its title and order too), so its pages errors show on the next run.

MessageFix
content/docs/billing/meta.json: pages: "refunds" is not a page or folder in its folderAdd refunds.md (or refunds/), or remove the name
content/docs/billing/meta.json: pages: "plans" is listed more than onceRemove the repeat
content/docs/billing/meta.json: Unrecognized key: "icon" (meta.json takes "title" and "pages")Remove the key
content/docs/billing/meta.json: invalid JSON (…)Fix the JSON (a trailing comma, usually)
content/docs/old/meta.json: no pages in its folderDelete the meta.json, or add pages
content/docs/a/b/c/meta.json: too deep for a meta.json; pages go at most 3 levels deep, e.g. section/group/pageMove the folder up a level
content/docs/a/b/c/d.md: slug: must have at most 3 segments, e.g. section/group/pageMove the page up a level
content/docs/Billing_FAQ.md: slug: must be lowercase words joined by hyphens, in folders, e.g. guides/installRename the file or folder (billing-faq.md)
content/docs/billing.md, content/docs/billing/index.md: more than one entry has the slug "billing"Keep one of the two
content/docs/faq.md: (frontmatter): Unrecognized key: "date"Remove the field, or add it to the schema (see Frontmatter)
content/docs/faq.md: updated: must be an ISO date, e.g. 2026-03-04, or another fieldFix the frontmatter (see Frontmatter)
move routes/docs/search.json.ts to routes/help/search.json.ts: …See Moving the Docs
the docs search index is about … KBSee Search

The dev server shows them too: a frontmatter or slug error when you open a page, and meta.json problems (invalid JSON included) as a docs: the page tree left these out warning in the terminal, while the sidebar skips what's wrong and keeps working. vp build doesn't validate, so keep the unit tests in CI.

Renaming a Page

The file path is the URL, so moving billing/invoices.md breaks links to /docs/billing/invoices. Add a permanent redirect in apps/web/void.config.ts, as for the blog:

routing: {
isr: true,
redirects: {
'/docs/billing/invoices': { to: '/docs/account/invoices', status: 301 },
'/*/docs/billing/invoices': { to: '/:splat/docs/account/invoices', status: 301 },
},
},

Links inside your docs are absolute (/docs/billing/plans): update them when a page moves.

Moving the Docs

To serve the docs at /help:

  1. Set basePath: '/help' on docs in config/content.config.ts.
  2. Move pages/(marketing)/docs/ to pages/(marketing)/help/ and routes/docs/ to routes/help/ (search fetches /help/search.json). Check the docs browser tests against the new path.
  3. Update the links in config/marketing-navigation.config.ts, and redirect the old URLs in void.config.ts: '/docs/*': { to: '/help/:splat', status: 301 }.

The content folder keeps its name, content/docs/.

Replace or Remove the Docs

Replace: delete the demo files and folders in content/docs/ and add yours. The e2e specs (apps/e2e/tests/marketing/docs*.spec.ts) don't depend on the demo's text.

Remove: delete content/docs/, pages/(marketing)/docs/, and routes/docs/; remove docs from config/content.config.ts and config/content.server.ts, the /docs links from config/marketing-navigation.config.ts, the docs blocks from config/__tests__/content.test.ts, and apps/e2e/tests/marketing/docs*. Then run pnpm check.

Translations

One file serves every locale: once you add Italian (it), /it/docs/billing/plans shows the same page with the chrome (sidebar labels, search, pager) in Italian, and search results keep the /it prefix. Labels live in messages/<locale>/marketing.json → docs. Pages written per language are not supported.

Design

DocsPage (@kit/content/ui) composes small blocks from @kit/content/react: DocsLayout, DocsSidebar, DocsSidebarSheet, DocsHeader, DocsBreadcrumbs, DocsToc, DocsTocDisclosure, DocsPager, DocsSearch and DocsSearchTrigger. To reorder, drop or restyle them, compose your own page component from those blocks and render it from the pages/(marketing)/docs/ pages instead of DocsPage, or edit the package. Its labels are the kit namespace content (packages/i18n/src/messages/<locale>/content.json).

  • Body typography is .content-body in apps/web/styles/makerkit.css, with the docs rules under [data-layout='docs'].
  • The sidebar and "On this page" stick below the header at 6rem; if your header is taller, set the offset in makerkit.css: :root { --docs-sticky-top: 7rem; }.
  • Docs use a wider frame than the rest of the site, and the header widens to match on docs pages (makerkit.css).

From a CMS

Docs can come from a CMS through a ContentSource, like the blog (Content Sources): set kind: 'remote' and maxAge on the docs collection and pass your source in config/content.server.ts. Slugs keep their folders (billing/payment-methods/cards); meta.json is a repository file, so order CMS pages with order and title folders through their index page. A CMS entry deeper than three levels, or with an empty slug, is skipped and logged. The search index refreshes with the pages, after maxAge.

Not Supported

  • Versioned docs (/docs/v1, /docs/v2)
  • Pages written per language (see Translations)
  • MDX or React components in pages, tabs, steps or cards
  • API reference generated from an OpenAPI spec
  • Checking or rewriting links between pages
  • A Markdown route per page and "Edit this page" links (the site-wide /llms.txt does list the docs: SEO)

Raw HTML and Security

As on the blog, raw HTML in Markdown is rendered as written, <script> included, on pages cached without a Content Security Policy: review docs pull requests like code. Search results are shown as text, so markup in a page never runs from the search. Frontmatter and meta.json are public.


Next: Content Sources →