Maintaining the docs¶

This site is built with MkDocs + Material for MkDocs, with Mermaid diagrams and multi-language support via mkdocs-static-i18n.

Build & preview locally¶

python3 -m venv .venv
source .venv/bin/activate
pip install -r docs/requirements.txt

mkdocs serve          # live-reload preview at http://127.0.0.1:8000
mkdocs build --strict # one-shot build; fails on broken links/refs

Layout¶

mkdocs.yml            # site config, theme, nav, i18n languages
docs/
  index.md            # home
  quickstart.md
  configuration.md
  flags.md
  architecture.md
  block-store.md
  archive.md
  networking.md
  bnb.md
  versioning.md
  maintaining-docs.md
  requirements.txt    # build dependencies

Diagrams (Mermaid)¶

Use a fenced ```mermaid block — Material renders it client-side:

```mermaid
flowchart LR
    A --> B
```

Multiple languages¶

Languages are declared in mkdocs.yml under the i18n plugin: en (default), de, it, fr, es, ru, zh (Chinese), ja.

Locale codes are ISO 639, not country codes

Chinese is zh, not cn — the theme keys translations by language code. Files therefore use <page>.zh.md.

Today only English has content; every other language falls back to English automatically, so the site is complete in all languages from day one.

To translate a page, add a sibling file with the locale suffix — the plugin uses the suffix structure:

docs/quickstart.md       # English (default)
docs/quickstart.de.md    # German
docs/quickstart.ja.md    # Japanese

Any page without a translation for a given locale shows the English version. No config change is needed to add a translation — just add the file.

Keeping docs in sync with the code¶

These pages describe live behaviour, so they go stale when the code changes. When a change touches any of the following, update the matching page in the same PR:

Code change	Page to update
A flag in `cmd/root.go`	CLI flags, Configuration
A config field in `ethereum/config.go`	Configuration
The segment store format / behaviour (`store/segment`)	Block store
The segment archive (`archive`, the `--archive-` / `--s3-` / `--r2-*` flags)	Segment archive, CLI flags, Configuration
Discovery / handshake / peer inventory	Networking & peers
A new subsystem or milestone (sync, RPC)	Architecture, Home status note
A version bump (`version/VERSION`)	Versioning

If a doc and the code disagree, the code is the source of truth — fix the doc.