Ysra Docs

Writing docs

How to add a page, put it in the navigation, preview it locally and get it through the build checks.

On this page

The docs are Markdown files in docs/, built by MkDocs into a static site. Engineering details — the theme, the build and deployment — are in the repository's README.md.

Preview locally#

$ uv sync
$ uv run mkdocs serve
INFO    -  [21:04:11] Serving on http://127.0.0.1:8001/

Pages reload as you save.

Add a page#

Create the file#

Put it in the folder of its section. File and folder names become the URL: docs/guides/deploy-previews.md is served at /guides/deploy-previews/.

Add front matter#

---
title: Deploy previews
description: One sentence, under 160 characters, saying what the page lets the reader do.
---

title is the page heading — do not repeat it as a # heading in the body. description is the lede under the title, the search-result summary and the social-card text, so write it for someone deciding whether to read on.

Optional keys: sidebar_title (a shorter nav label), status (new, beta or deprecated), toc: false, image (a social card) and noindex: true.

Add it to the navigation#

Navigation is explicit, in mkdocs.yml:

mkdocs.yml
nav:
  - Guides:
      - Change an existing repository: guides/existing-repository.md
      - Deploy previews: guides/deploy-previews.md

Sections nest to any depth; the sidebar and mobile drawer follow. A page that is not in nav fails the build.

Build it the way CI does#

$ make check

This builds with --strict and then checks the generated site.

Reuse a fragment#

Text that must stay identical on several pages — a warning, a prerequisite — lives once in docs/_snippets/ and is included where it is needed:

--8<-- "sandbox-base-url.md"

The build fails if the file does not exist. Snippet files are not pages and never appear in the navigation.

What the checks catch#

Check Fails on
mkdocs build --strict Broken links and anchors, pages missing from nav, root-absolute links, invalid config.
scripts/check_site.py Markdown that did not render (a stray !!! or fence), missing titles or descriptions, duplicate IDs, broken asset or navigation links, images without alt text.

Style#

  • Lead with the task. Headings name what the reader is doing — "Set the budget", not "Budget configuration".
  • Link relatively to the Markdown file: [Previews](../developer/previews.md). Never /developer/previews/ — that breaks under versioned URLs.
  • Show real values. Field names, defaults and status codes come from the API, not from memory. When a behaviour depends on configuration, say so.
  • One callout per screen at most. See Components for every building block.
YsraDocs