Rayhaan JaufeerallyandClaude Fable 5.1
7b6547d3c9
The documentation sources are Zola Markdown: front matter between +++ lines, shortcodes that insert the example configurations, and @/ internal links. A code forge shows all three unrendered, which the README used to deny. A docs/README.md now explains each, and the README points to it. "Configuring BGP Neighbors" becomes "BGP Neighbors", as the other feature pages are titled; "When a Neighbor Restarts" becomes "Neighbor Restart", a noun phrase as the style guide asks. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
29 lines
1.1 KiB
Markdown
29 lines
1.1 KiB
Markdown
# 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.
|