docs: align consensus references and guides with current behavior

.gitattributes

@@ -0,0 +1,2 @@
+# Keep the vendored Mermaid distribution byte-for-byte identical to Platform.
+book/mermaid.min.js -whitespace linguist-vendored=true

.github/workflows/docs-deployment.yml

@@ -1,62 +1,83 @@
-# Build and deploy the docs.tendermint.com website content.
-# The static content is published to GitHub Pages.
-#
-# For documentation build info, see docs/DOCS_README.md.
-name: Build static documentation site
+name: Build and deploy documentation
+
 on:
-  workflow_dispatch:  # allow manual updates
+  pull_request:
+    paths:
+      - 'book/**'
+      - 'docs/**'
+      - 'spec/**'
+      - 'rpc/openapi/**'
+      - 'scripts/prepare-docs.py'
+      - 'scripts/check-docs.py'
+      - 'scripts/tests/test_prepare_docs.py'
+      - 'Makefile'
+      - '.github/workflows/docs-deployment.yml'
   push:
     branches:
-      - master
+      - v1.8-dev
     paths:
-      - docs/**
-      - spec/**
+      - 'book/**'
+      - 'docs/**'
+      - 'spec/**'
+      - 'rpc/openapi/**'
+      - 'scripts/prepare-docs.py'
+      - 'scripts/check-docs.py'
+      - 'scripts/tests/test_prepare_docs.py'
+      - 'Makefile'
+      - '.github/workflows/docs-deployment.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  # This is split into two jobs so that the build, which runs npm, does not
-  # have write access to anything. The deploy requires write access to publish
-  # to the branch used by GitHub Pages, however, so we can't just make the
-  # whole workflow read-only.
   build:
-    name: VuePress build
-    runs-on: ubuntu-latest
-    container:
-      image: alpine:latest
-    permissions:
-      contents: read
+    name: Build mdBook and RPC documentation
+    runs-on: ubuntu-24.04
     steps:
-      - name: Install generator dependencies
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - name: Install mdBook (same version as Platform)
         run: |
-          apk add --no-cache make bash git npm
-      - uses: actions/checkout@v7
-        with:
-          # We need to fetch full history so the backport branches for previous
-          # versions will be available for the build.
-          fetch-depth: 0
+          curl --fail --location --silent --show-error \
+            https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz \
+            --output "$RUNNER_TEMP/mdbook.tar.gz"
+          echo "9ef07fd288ba58ff3b99d1c94e6d414d431c9a61fdb20348e5beb74b823d546b  $RUNNER_TEMP/mdbook.tar.gz" | sha256sum --check
+          mkdir -p "$HOME/.local/bin"
+          tar -xzf "$RUNNER_TEMP/mdbook.tar.gz" -C "$HOME/.local/bin"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Test documentation staging
+        run: python3 -m unittest discover -s scripts/tests -p test_prepare_docs.py
       - name: Build documentation
-        run: |
-          git config --global --add safe.directory "$PWD"
-          make build-docs
-      - uses: actions/upload-artifact@v7
+        run: make build-docs
+      - name: Upload preview
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: documentation-preview
+          path: book/book
+          retention-days: 14
+          if-no-files-found: error
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/v1.8-dev'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
         with:
-          name: build-output
-          path: ~/output/
+          path: book/book
 
   deploy:
     name: Deploy to GitHub Pages
-    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/v1.8-dev'
     needs: build
+    runs-on: ubuntu-24.04
     permissions:
-      contents: write
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/download-artifact@v8
-        with:
-          name: build-output
-          path: ~/output
-      - name: Deploy to GitHub Pages
-        uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          branch: 'docs-tendermint-com'
-          folder: ~/output
-          single-commit: true
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5

.gitignore

@@ -25,12 +25,6 @@ addrbook.json
 artifacts/*
 build/*
 coverage.txt
-docs/.vuepress/dist
-docs/_build
-docs/dist
-docs/node_modules/
-docs/spec
-docs/.vuepress/public/rpc
 index.html.md
 libs/pubsub/query/fuzz_test/output
 profile\.out
@@ -64,3 +58,15 @@ proto/spec/**/*.pb.go
 *.gz
 *.dvi
 .gocache
+
+# Legacy local VuePress output
+/docs/.vuepress/
+/docs/node_modules/
+/docs/_build/
+/docs/dist/
+/docs/spec/
+
+# Generated mdBook sources and HTML
+/book/src/
+/book/book/
+__pycache__/

Makefile

@@ -330,20 +330,22 @@ DESTINATION = ./index.html.md
 ###############################################################################
 ###                           Documentation                                 ###
 ###############################################################################
-# todo remove once tendermint.com DNS is solved
-build-docs:
-	@cd docs && \
-	while read -r branch path_prefix; do \
-		( git checkout $${branch} && npm ci --quiet && \
-			VUEPRESS_BASE="/$${path_prefix}/" npm run build --quiet ) ; \
-		mkdir -p ~/output/$${path_prefix} ; \
-		cp -r .vuepress/dist/* ~/output/$${path_prefix}/ ; \
-		cp ~/output/$${path_prefix}/index.html ~/output ; \
-	done < versions ; \
-	mkdir -p ~/output/master ; \
-	cp -r .vuepress/dist/* ~/output/master/
+MDBOOK ?= mdbook
+DOCS_SOURCE_REF ?= $(shell git rev-parse HEAD)
+
+prepare-docs:
+	python3 scripts/prepare-docs.py --source-ref "$(DOCS_SOURCE_REF)"
+.PHONY: prepare-docs
+
+build-docs: prepare-docs
+	$(MDBOOK) build book
+	python3 scripts/check-docs.py book/book
 .PHONY: build-docs
 
+serve-docs: prepare-docs
+	$(MDBOOK) serve book
+.PHONY: serve-docs
+
 ###############################################################################
 ###                            Docker image                                 ###
 ###############################################################################

README.md

@@ -1,7 +1,5 @@
 # Tenderdash
 
-![banner](docs/tendermint-core-image.jpg)
-
 [Byzantine-Fault Tolerant](https://en.wikipedia.org/wiki/Byzantine_fault_tolerance)
 [State Machine Replication](https://en.wikipedia.org/wiki/State_machine_replication).
 Or [Blockchain](<https://en.wikipedia.org/wiki/Blockchain_(database)>), for short.
@@ -20,17 +18,18 @@ written in any programming language - and securely replicates it on many machine
 ## Background
 
 Tenderdash started as a fork of the [Tendermint Core](https://www.github.com/tendermint/tendermint)
-project and has been used in public environments such as the Cosmos Network. Although based on
+project, which has been used in public environments such as the Cosmos Network. Although based on
 Tendermint, Tenderdash differs from Tendermint through its use of Dash's [long-living masternode
 quorums (LLMQs)](https://github.com/dashpay/dips/blob/master/dip-0006.md) to support threshold
 signatures, quorum-based voting, and dynamic validator set rotation. These enhancements to support
 rapid transaction finality and maintain strong security guarantees make Tenderdash ideal for Dash
 Platform’s needs.
 
-For Tendermint protocol details, refer to the [Tendermint Specification](./spec/README.md). For a
-detailed analysis of the consensus protocol, including safety and liveness proofs, read the
-Tendermint paper, "[The latest gossip on BFT consensus](https://arxiv.org/abs/1807.04938)".
-Tendermint documentation can be found on [docs.tendermint.com](https://docs.tendermint.com/).
+For Tenderdash protocol details, refer to the [protocol specifications](./spec/README.md)
+and the [source-derived consensus protocol](./spec/consensus/consensus.md).
+The [documentation guide](./docs/DOCS_README.md) explains how to build and preview
+the complete mdBook site. For the original consensus research, read
+"[The latest gossip on BFT consensus](https://arxiv.org/abs/1807.04938)".
 
 ## Releases
 
@@ -76,7 +75,7 @@ recommend keeping Tenderdash up-to-date.
 
 Before contributing to the project, please take a look at the [contributing
 guidelines](CONTRIBUTING.md) and the [style guide](STYLE_GUIDE.md). You may also find it helpful to
-read the [Tendermint specifications](./spec/README.md), and familiarize yourself with the
+read the [Tenderdash specifications](./spec/README.md), and familiarize yourself with the
 [Architectural Decision Records (ADRs)](./docs/architecture/) and [Request For Comments
 (RFCs)](./docs/rfc/).
 

book/README.md

@@ -0,0 +1,15 @@
+# Tenderdash Documentation
+
+Tenderdash is the Byzantine Fault Tolerant consensus engine used by Dash Platform.
+
+- [Guides and introduction](docs/README.md)
+- [Operating nodes](docs/nodes/README.md)
+- [Application development](docs/app-dev/readme.md)
+- [Protocol specifications](spec/README.md)
+- [Consensus protocol](spec/consensus/consensus.md)
+- [RPC API](api/rpc/index.html)
+- [Build and contribute to this documentation](docs/DOCS_README.md)
+
+The consensus specification covers the primary flow of a height, transitions and
+decision rules, alternative flows, commit handling, recovery, and known discrepancies.
+Use the sidebar or search to explore the complete documentation.