---
title: Writing docs
description: How a folder of markdown becomes a site — the supported syntax, front matter, navigation, assets, and redirects.
order: 2
---

# 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](/writing/markdown) — exactly which syntax is supported.
- [Front matter](/writing/front-matter) — title, description, ordering.
- [Folders and navigation](/writing/navigation) — how the sidebar is built.
- [Images and assets](/writing/assets) — uploading and referencing files.
- [Redirects](/writing/redirects) — keeping old URLs alive.