# Help Docs

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/marketing/help-docs*

---

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](./blog-and-changelog); to read pages from a CMS instead, see [Content Sources](./content-sources).

This page is part of the [Marketing documentation](./overview).

{% img src="/assets/images/docs/void-cloudflare/help-center.png" width="1440" height="900" alt="The product help center with its sidebar and table of contents." /%}

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

## What's Where

| Part | Location |
|---|---|
| Pages and folder order | `apps/web/content/docs/**/*.md`, `meta.json` per folder |
| Collection, frontmatter fields | `apps/web/config/content.config.ts` → `docs` |
| Pages | `apps/web/pages/(marketing)/docs/` (`index`, `[slug]`, `[section]/[slug]`, `[section]/[group]/[slug]`) |
| Page composition | `DocsPage` from `@kit/content/ui` (`packages/content/src/ui/docs-page.tsx`); app bindings in `apps/web/components/content-ui.tsx` |
| Search index | `apps/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`:

```md
---
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:

| Level | Example file | Shown as |
|---|---|---|
| Page | `content/docs/faq.md` | A link at the sidebar's top level, among the sections |
| Section | `content/docs/billing/plans.md` | A bold heading with its pages under it |
| Group | `content/docs/billing/payment-methods/cards.md` | A 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:

```json
{
  "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`:

```md
---
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

| Field | Required | Notes |
|---|---|---|
| `title` | yes | The page's `<h1>`, `<title>`, sidebar link and search result |
| `description` | yes | Under the title, `<meta name="description">`, and searched |
| `order` | no | A whole number; places the page among those `meta.json` doesn't list |
| `updated` | no | ISO date (`2026-10-30`), shown as "Updated October 30, 2026" |
| `status` | no | `published` (default) or `draft` |
| `image` | no | A 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.

## Search

⌘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](https://github.com/lucaong/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.

| Message | Fix |
|---|---|
| `content/docs/billing/meta.json: pages: "refunds" is not a page or folder in its folder` | Add `refunds.md` (or `refunds/`), or remove the name |
| `content/docs/billing/meta.json: pages: "plans" is listed more than once` | Remove 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 folder` | Delete 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/page` | Move the folder up a level |
| `content/docs/a/b/c/d.md: slug: must have at most 3 segments, e.g. section/group/page` | Move the page up a level |
| `content/docs/Billing_FAQ.md: slug: must be lowercase words joined by hyphens, in folders, e.g. guides/install` | Rename 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](#frontmatter)) |
| `content/docs/faq.md: updated: must be an ISO date, e.g. 2026-03-04`, or another field | Fix the frontmatter (see [Frontmatter](#frontmatter)) |
| `move routes/docs/search.json.ts to routes/help/search.json.ts: …` | See [Moving the Docs](#moving-the-docs) |
| `the docs search index is about … KB` | See [Search](#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:

```ts
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](./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](#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](./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 →](./content-sources)
