# Writing docs

> Markdown, MDX, and the docs.json that shapes your site.

Everything Stipple builds comes from plain files in your repository. There is no database and no proprietary format — if you leave, your docs are exactly where they always were.

## Pages

Every `.md` or `.mdx` file in your docs folder becomes a page. Frontmatter sets the title and description:

```markdown
---
title: Authentication
description: How to authenticate against the API.
---
```

Code blocks, callouts, tables, and images all work out of the box. MDX components are available for richer layouts.

## Navigation

`docs.json` defines the sidebar. Pages are referenced by their file name without the extension; groups render as sections:

```json
{
  "nav": [
    { "group": "Guides", "pages": ["authentication", "webhooks"] }
  ]
}
```

Pages not listed in `nav` still build, but are unlisted: excluded from search, the sitemap, and `llms.txt`.

## Branding

`docs.json` also carries the site name, favicon, brand colors, and header links — so branding is versioned in git alongside everything else.