diff --git a/README.md b/README.md
index 055adbf..b1a9740 100644
--- a/README.md
+++ b/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
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..2c416af
--- /dev/null
+++ b/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.
diff --git a/docs/content/docs/getting-started/quick-start.md b/docs/content/docs/getting-started/quick-start.md
index 835b5ed..7fb4b5e 100644
--- a/docs/content/docs/getting-started/quick-start.md
+++ b/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)
diff --git a/docs/content/docs/guides/graceful-restart.md b/docs/content/docs/guides/graceful-restart.md
index 315b856..b3014a7 100644
--- a/docs/content/docs/guides/graceful-restart.md
+++ b/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:
diff --git a/docs/content/docs/guides/peers.md b/docs/content/docs/guides/peers.md
index dda70e2..ba4f5fc 100644
--- a/docs/content/docs/guides/peers.md
+++ b/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