# kat5200 User Guide

Source for the kat5200 user guide, built with [MkDocs](https://www.mkdocs.org/) and the
[Material](https://squidfunk.github.io/mkdocs-material/) theme.

## Editing

Content lives in `docs/`. The site structure and theme are configured in `mkdocs.yml`.

## Live preview

```bash
cd doc/guide
mkdocs serve
```

Then open <http://127.0.0.1:8000>.

## Build

```bash
cd doc/guide
mkdocs build --strict
```

Output is written to `site/` (gitignored).

## PDF export

A single PDF is generated by the `mkdocs-with-pdf` plugin (rendered with WeasyPrint).
WeasyPrint, mkdocs, and the theme come from the system (pacman); the plugin is not
packaged for Arch, so it lives in a local venv created with `--system-site-packages`.

One-time setup:

```bash
cd doc/guide
./setup-venv.sh
```

Build the PDF (output: `site/pdf/kat5200-user-guide.pdf`):

```bash
./build-pdf.sh
```

The packaged/distributed PDF is committed at `doc/kat5200-user-guide.pdf` so
Windows/MSYS package builds do not need the PDF toolchain. After regenerating
the PDF, refresh that committed copy from the repo root:

```bash
cmake -E copy_if_different doc/guide/site/pdf/kat5200-user-guide.pdf doc/kat5200-user-guide.pdf
```

PDF export is kept separate from the normal site build via `mkdocs-pdf.yml`
(which `INHERIT`s `mkdocs.yml`), so a plain `mkdocs build` does **not** require the
plugin. Harmless `Fontconfig`/`VORG table` messages may appear during rendering.

## Dependencies

Building the guide requires `mkdocs`, `mkdocs-material`, and **pymdown-extensions**
(used for keyboard-key styling, tabbed content, collapsible blocks, and code
highlighting). On Arch:

```bash
sudo pacman -S mkdocs mkdocs-material python-pymdown-extensions
```

## Status

This is a first-pass guide. Some content is derived from the older `doc/kat5200.texi`,
which predates the current SDL3 / Nuklear / TOML-config build; where the running program
disagrees with the docs, the program is authoritative.
