Documentation style guide

Voice

• Address the reader as "you". Use the present tense and the active voice.
• Lead with what the reader can do, then explain how it works.
• Keep sentences short. Prefer a table over a long list of conditions.

Names

• The framework is Riverbase. Crates are riverbase_core, riverbase_http, and so on, always in code formatting.
• Environment variables use the RIVERBASE_ prefix, and the config file is riverbase.toml.
• Example namespaces use riverbase.<domain>, such as riverbase.todo.
• npm run lint:naming fails the build if a legacy name appears anywhere in the site.

Code samples

• Samples are written against the published crates in riverbase-io/riverbase, never invented. If an API is not in the source, it does not go in the docs. npm run check:snippets verifies identifiers.
• Document only published crates.
• Give multi-line samples a title="path/to/file.rs".
• Prefer complete, compilable snippets for short examples. Use /* … */ only for elided bodies.
• Show HTTP calls as curl with the full path, including api_base.

Structure

• Every page has front matter with a title and a one-sentence description.
• Crate pages start with <CrateBadge name="…" />.
• Use <HttpRoute method="…" path="…"> to list routes, and Mermaid for flows and architecture.
• Link to other pages by relative file path (../crates/core/index.md), so broken links fail the build.