Building the documentation

Tenderdash uses mdBook, like the Dash Platform book. The site includes the guides in docs/, all Markdown specifications in spec/, and the RPC reference from rpc/openapi/.

Local build

Install Python 3.10 or later and mdBook 0.4.40 (the version used by Platform):

cargo install mdbook --version 0.4.40 --locked
make build-docs

Run make serve-docs and open http://localhost:3000/. To serve an existing build, run python3 -m http.server 8000 --directory book/book and open http://localhost:8000/. Use HTTP so the RPC reference can fetch its schema. MDBOOK=/path/to/mdbook make build-docs selects a particular binary. For guides and specifications, edit their canonical files in docs/ or spec/, then run the build again. When using the server, rerun make prepare-docs after editing canonical files; mdBook watches the staged copies.

book/SUMMARY.md defines the navigation. Add every new Markdown page there; the build fails if a source page is missing from the summary or a summary entry has no source file. The HTML build also rejects missing local pages or assets. The consensus protocol and all its companion chapters are listed explicitly under Protocol specifications.

The preparation script copies sources and assets into ignored book/src/, strips VuePress metadata, resolves directory links, and points links to repository source files at the build's Git revision. It also stages the RPC reference at api/rpc/. It does not switch branches or modify documentation sources. Both book/src/ and book/book/ are disposable build output. Set DOCS_SOURCE_REF to override the Git revision used for source links.

Use fenced mermaid blocks for diagrams. The book uses the same vendored Mermaid 11.6.0 distribution as Platform; its MIT license is in book/mermaid-LICENSE. Diagrams render locally without a CDN. mdBook provides local full-text search without an external search service.

Preview and publishing

.github/workflows/docs-deployment.yml builds pull requests and uploads a documentation-preview artifact. Download it and extract it, then run python3 -m http.server 8000 from the extracted directory and open http://localhost:8000/. The RPC reference requires HTTP serving. Pull requests have read-only repository permissions and cannot deploy.

Pushes to the repository's default branch publish the same output using GitHub Pages artifacts and the github-pages environment, like Platform. This follows default-branch changes without editing the workflow.

To publish another branch manually, open the workflow in Actions, choose Run workflow, and select the branch. The workflow must exist on the default branch for GitHub to show that control. In Settings → Pages, select GitHub Actions as the build source. The github-pages environment's deployment rules must permit the default branch and any branches selected for manual publication. The workflow reports the deployed URL. Ordinary pushes to other branches do not publish; pull requests remain previews.

Naming and attribution

Use Tenderdash for this product, its CLI, and current source links. Preserve copyright notices, original research titles and citations, external project names, and identifiers required by the implementation, such as tendermint.abci, JSON public-key type names, metric names, and TLA+/Ivy module names. Do not rename wire types to change their display name.

Generate the ABCI API page from its protobuf source with make proto-doc; spec/abci/api.md is generated and must not be edited by hand.