Writing docs

Write in a folder of Markdown files. Docsary keeps the source and publishes a rendered page with navigation and search. You can export the original Markdown at any time.

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, mcp, skill, skill.md

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.

A page name may not end in .md once the extension is stripped: notes.md.md is rejected, because /notes.md is where page notes serves its Markdown. Nor may a page end up at index: index/index.md is rejected, because /index is the front page. A root index.md (or README.md) is the front page, as always.

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.