# Documentation sources

This directory holds the sources of the Ferrix documentation site, built
with [Zola](https://www.getzola.org):

```bash
zola --root docs serve     # http://127.0.0.1:1111, rebuilt on every change
zola --root docs build     # into docs/public
```

The pages under `content/` are Markdown with Zola additions, which a code
forge does not render:

- The block between `+++` lines at the top of each page is its front
  matter: the title, description and position in the navigation.
- `{{ example(name="...") }}` and `{{ file(name="...") }}` insert a file
  from [`examples/`](examples/), whole, at that point. Open the file to
  read it.
- Links of the form `@/docs/...` are internal links that Zola resolves and
  checks at build time. On the forge they do not work; the target is the
  path after `@/`, under `content/`.

To read the documentation as intended, build the site, or read it where
it is published (`base_url` in [`config.toml`](config.toml)).

`STYLE.md` is the writing guide. CI builds the site on every push and fails
on a link to a page or an anchor that does not exist; `zola --root docs
check` also checks external links.