Writing docs

Your source of truth is a folder of .md files. Docsary takes that folder as it is: your markdown is kept exactly as you wrote it and served alongside the rendered page, so nothing you push is ever converted into a format you cannot get back.

The shape of a docs folder

docs/
  index.md                    →  /
  quickstart.md               →  /quickstart
  guide/
    index.md                  →  /guide
    install.md                →  /guide/install
    configure.md              →  /guide/configure
  reference/
    api.md                    →  /reference/api

Four rules cover the mapping:

1. The .md extension is stripped.
2. index.md and README.md drop out of the path, so guide/index.md serves at /guide.
3. Paths are lowercased.
4. index.md at the root becomes the empty path — the version's home page.

A page path must match ^[a-z0-9][a-z0-9._-]*(/[a-z0-9][a-z0-9._-]*)*$ after lowercasing. Letters, digits, dots, underscores, and hyphens only. Spaces are not allowed — getting started.md is rejected, getting-started.md is fine. Rejected files come back in the rejected array of the import response, and the push script exits non-zero when that array is non-empty.

Reserved paths

A top-level page may not use a path the serving router owns:

assets, search, v1, __api, __health, __bench, llms.txt, llms-full.txt, sitemap.xml, robots.txt, manifest.webmanifest, sw.js

A top-level page also may not collide with one of the site's version slugs. These are checked against the first path segment, so reference/assets.md is fine — only assets.md at the root is not.

In this section

• Markdown reference — exactly which syntax is supported.
• Front matter — title, description, ordering.
• Folders and navigation — how the sidebar is built.
• Images and assets — uploading and referencing files.
• Redirects — keeping old URLs alive.