Unified documentation site for the Bitcoin Commons BLVM ecosystem, built with mdBook and hosted on GitHub Pages.
This repository builds the docs.thebitcoincommons.org site with mdBook. Most chapters are written in src/ here. A few pages embed upstream Markdown at build time via mdBook's {{#include}} from modules/governance/ (governance narrative and config YAML checked in CI, see .github/workflows/deploy.yml). The Orange Paper and Consensus Spec are published on the Bitcoin Commons website, not embedded in this book (pointer chapter). Governance policy numbers in wired chapters use [[gov:KEY]] placeholders expanded by mdbook-governance-vars at build time, edit governance config/*.yml, not hand-copied literals (see docs/GOVERNANCE_MDBOOK.md and mdbook-governance-vars/README.md). Optional git submodules under modules/ can mirror upstream repos for local work. Component-specific documentation (for example under blvm-consensus/docs/) remains in each crate's repository; this book links there or summarizes unless you add an explicit include.
Live Site: docs.thebitcoincommons.org
book.toml- mdBook configurationsrc/- Documentation source files and navigation structuremodules/- Governance sources included into the book; see Local Development.github/workflows/- Automated build and deployment
- Clone this repository:
git clone https://github.com/BTCDecoded/blvm-docs.git- Wire
modules/includes (required formdbook buildwhen using governance includes). Pages that use{{#include}}expect at least:
modules/governance/README.mdandmodules/governance/GOVERNANCE.md- Deploy CI also expects
modules/governance/config/action-tiers.yml,repository-layers.yml, andemergency-tiers.yml(for policy parity checks); clone governance fully if you rely on those paths locally.
Clone governance if needed. If you keep it as a sibling directory next to blvm-docs, symlink from blvm-docs/modules/:
cd blvm-docs/modules
ln -sf ../../governance governanceAdjust paths for your checkout. CI clones these repos instead of symlinks. If git status errors with expected submodule path … not to be a symbolic link, use git -c submodule.recurse=false status or git submodule update --init for modules/governance instead of a symlink.
- Install the governance preprocessor (expands
[[gov:KEY]]from YAML):
cargo install --locked --path mdbook-governance-varsOptional checks (same order as CI):
./scripts/verify-book-inputs.sh # includes governance literal check
cargo test --locked --manifest-path mdbook-governance-vars/Cargo.tomlThe drift tests fail if governance/config/*.yml disagrees with blvm-commons threshold.rs (see docs/GOVERNANCE_MDBOOK.md).
- Serve the documentation locally:
mdbook serveThe documentation will be available at http://localhost:3000
- Build the documentation:
mdbook buildOutput will be in the book/ directory.
The optional modules/blvm git submodule is the meta-repo umbrella (blvm). Its docs/ tree covers release/CI workflows for that repo. The canonical narrative for docs.thebitcoincommons.org lives in src/ in this repository.
The book chapter src/getting-started/installation.md is timeless: it points operators to btcdecoded.org/install for versioned downloads, filenames, and checksum commands. Edit that Markdown directly; the website repo owns release-driven install JSON via fetch-blvm-release.mjs.
src/: primary narrative,SUMMARY.mdnavigation, and most chapters shipped on the site.{{#include}}: atmdbook build, pulls specific files frommodules/(paths listed under Local Development). This is not a wholesale sync of every upstream doc; only wired paths are embedded.- Upstream repositories: detailed per-crate docs and READMEs live beside code; the book links to GitHub or tells readers to run
cargo docwhere the API Index describes.
See CONTRIBUTING.md and Contributing to BLVM Documentation (in the built book: Appendices → Contributing to Documentation).
Documentation is automatically built and deployed to GitHub Pages on every push to the main branch via GitHub Actions.
MIT License - see LICENSE for details.