Docs: say what the forge cannot render, and two headings by the style guide

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>

README.md

@@ -89,9 +89,11 @@ privileges, the systemd unit, and upgrading without withdrawing routes.
 ## Documentation
 
 The documentation is a website built from [`docs/`](docs/) with
-[Zola](https://www.getzola.org) (`zola --root docs serve`, then
-<http://127.0.0.1:1111>). The pages are plain Markdown and can be read
-in the repository:
+[Zola](https://www.getzola.org): `zola --root docs serve`, then open
+<http://127.0.0.1:1111>. The sources are Markdown with Zola front matter,
+shortcodes and internal links, so the forge shows them with those parts
+unrendered; [`docs/README.md`](docs/README.md) explains what each is. The
+pages:
 
 - [Overview](docs/content/docs/getting-started/introduction.md),
   [installation](docs/content/docs/getting-started/installation.md) and

docs/README.md

@@ -0,0 +1,28 @@
+# 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.

docs/content/docs/getting-started/quick-start.md

@@ -112,6 +112,6 @@ this metric, see [Monitoring Ferrix](@/docs/operations/monitoring.md#alerting-ru
 
 ## Next Steps
 
-- [Configuring BGP Neighbors](@/docs/guides/peers.md)
+- [BGP Neighbors](@/docs/guides/peers.md)
 - [Import Policy](@/docs/guides/import-policy.md)
 - [Configuration Examples](@/docs/guides/examples.md)

docs/content/docs/guides/graceful-restart.md

@@ -77,7 +77,7 @@ When the daemon stops in response to SIGTERM, it ends each session for
 good. On a session on which the N bit is in use, it sends a Cease
 NOTIFICATION message with the subcode Hard Reset.
 
-## When a Neighbor Restarts
+## Neighbor Restart
 
 Ferrix retains the routes of a neighbor whose session ends in one of the
 following ways, if graceful restart is in use on the session:

docs/content/docs/guides/peers.md

@@ -1,5 +1,5 @@
 +++
-title = "Configuring BGP Neighbors"
+title = "BGP Neighbors"
 description = "Describes how to configure BGP neighbors, address families, link-local neighbors, ADD-PATH, and session timers, and how Ferrix filters inbound connections."
 weight = 1