docs: render documentation site with mdbook

[MegaRedHand]

Summary

Closes #122. Wires up mdbook so the existing docs/ markdown can be rendered as a browsable site.

Changes

• book.toml: mdbook config pointing src at docs/, with git-repository-url and an edit-url-template so each page links back to its source on main.
• docs/SUMMARY.md: required mdbook table of contents. Groups pages into two parts — Consensus (3SF-mini, LMD-GHOST) and Operations (Metrics, Checkpoint Sync, Fork Choice Visualization).
• docs/introduction.md: landing page that orients the reader and links to the existing docs/infographics/*.html (mdbook copies the HTML files into the rendered site as-is).
• Makefile: docs-deps (installs mdbook 0.4.51 via cargo), docs (one-shot build into ./book), docs-serve (live-reload preview).
• .gitignore: excludes the book/ build output.

No mdbook plugins are pulled in — none of the current docs use mermaid / katex / GFM alerts, so the bare renderer is enough. Plugins can be added later if/when content needs them, following the ethrex setup referenced in the issue.

Test plan

• make docs-deps installs mdbook (already cached locally; target verified)
• make docs builds successfully and produces a complete book/ site
• make docs-serve renders Introduction + Consensus + Operations sections in the sidebar with correct ordering
• Both infographics under docs/infographics/ are reachable from the introduction page
• CI workflow for building / publishing the docs left as a follow-up

[github-actions]

🤖 Kimi Code Review

Overall: This is a documentation infrastructure PR adding mdbook support. No consensus-critical code is modified, but there are structural issues that will break the documentation build.

Critical Issues

Missing source files (will break build)

• docs/SUMMARY.md references files not present in the diff: 3sf_mini.md, lmd_ghost.md, metrics.md, checkpoint_sync.md, fork_choice_visualization.md
• docs/introduction.md references infographics at ./infographics/3sf-mini-infographic.html and ./infographics/ethlambda_architecture.html which are not included

Without these files, mdbook build will fail with "file not found" errors. Either include the missing files in this PR or create placeholder files.

Security & Build Integrity

Makefile line 51: Add --locked to ensure reproducible builds and prevent dependency drift in the installed tool:

docs-deps:
	cargo install --locked --version 0.4.51 mdbook

book.toml line 8: Verify edition = "2024" compatibility. Rust 2024 edition requires Rust ≥1.85.0 (released Feb 2025). Ensure this matches the edition used in the project's Cargo.toml to avoid confusion.

Suggestions

Makefile line 54: Consider adding a check for the binary in docs target to provide a clearer error message:

docs:
	@which mdbook > /dev/null || (echo "mdbook not found. Run 'make docs-deps' first." && exit 1)
	mdbook build

book.toml line 6: The description contains "implementation" which is spelled correctly, but verify the title "ethlambda" matches the project's preferred capitalization elsewhere.

Verdict

The infrastructure setup is correct for mdbook, but do not merge until the missing markdown files and infographic assets are added or the SUMMARY/introduction is adjusted to reference only existing files.

---

Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt

[github-actions]

🤖 Claude Code Review

Here is the review for PR #326:

---

PR #326 — docs: render documentation site with mdbook

Overview: Pure documentation infra PR — wires up mdbook to render the existing docs/ markdown as a browsable site, with three new Makefile targets (docs-deps, docs, docs-serve), a book.toml config, a required SUMMARY.md, and a new introduction.md landing page. No runtime code is touched.

---

Potential Bug — broken "Edit this page" links

book.toml, line 14:

edit-url-template = "https://github.com/lambdaclass/ethlambda/edit/main/{path}"

In mdbook, {path} is resolved relative to the src directory (here docs/). So for docs/3sf_mini.md, the generated URL becomes:

https://github.com/lambdaclass/ethlambda/edit/main/3sf_mini.md   # 404

The correct template should include the docs/ prefix:

edit-url-template = "https://github.com/lambdaclass/ethlambda/edit/main/docs/{path}"

Without this fix, every "Edit this page" button in the rendered site will 404.

---

Minor Points

• docs / docs-serve have no dependency on docs-deps: Running make docs on a CI machine or a fresh clone where mdbook isn't installed will fail silently-ish with a "command not found". A comment in the Makefile or a command -v mdbook guard in the docs recipe would make the failure more actionable. Adding docs-deps as a prerequisite is another option, though it would re-invoke cargo install on every build (slow). At minimum, the README / CONTRIBUTING.md could document the make docs-deps step.

• [rust] section in book.toml: edition = "2024" controls the Rust edition for executable playground snippets. The current docs don't appear to have any runnable Rust blocks, so this is a no-op today. It's harmless and the value is correct for this codebase if snippets are added later — no action needed, just worth knowing.

• No CI job: Acknowledged as a follow-up in the PR description, so not blocking. Worth tracking so doc build regressions don't go unnoticed.

---

What Looks Good

• Version-pinned mdbook install (0.4.51) — good for reproducibility.
• All three new targets correctly added to .PHONY.
• SUMMARY.md grouping (Consensus / Operations) matches how the docs are actually structured.
• .gitignore entry for book/ is clean and correctly placed.
• Introduction page links and related-projects list are accurate and consistent with CLAUDE.md.
• fold = { enable = true, level = 1 } is a sensible default (collapsible but starts expanded).

---

Bottom line: One real bug (the broken edit-URL template), one mild DX rough edge (missing docs-deps dependency), and otherwise a clean, straightforward PR. Fix the template path before merging.

---

Automated review by Claude (Anthropic) · sonnet · custom prompt

[greptile-apps]

Greptile Summary

This PR wires up mdbook to render the existing docs/ markdown as a browsable site, adding book.toml, docs/SUMMARY.md, docs/introduction.md, three Makefile targets, and a .gitignore entry for the build output. All referenced source files and infographic assets are confirmed present, and the edit-url-template correctly resolves to include the docs/ prefix in mdBook ≥0.4.8.

Confidence Score: 4/5

Safe to merge — documentation-only change with one minor reproducibility suggestion on the cargo install invocation.

All changed files are documentation infrastructure with no application logic. The single finding is a P2 style suggestion (missing --locked on cargo install). No P0 or P1 issues found.

No files require special attention.

Important Files Changed

Filename	Overview
.gitignore	Adds book/ exclusion for mdbook build output — straightforward and correct.
Makefile	Adds docs-deps, docs, and docs-serve targets; cargo install is missing --locked for full reproducibility.
book.toml	New mdbook config with correct src = "docs", repo URL, and edit-url-template; {path} expands to include the docs/ prefix in mdbook ≥0.4.8 so edit links resolve correctly.
docs/SUMMARY.md	Required mdbook TOC; all referenced files confirmed present in the repo.
docs/introduction.md	Clean landing page; infographic HTML paths and external links all resolve correctly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[make docs-deps\ncargo install mdbook 0.4.51] --> B[make docs\nmdbook build]
    B --> C[book/ output directory]
    C --> D[book/index.html\nIntroduction]
    C --> E[book/3sf_mini.html\nConsensus: 3SF-mini]
    C --> F[book/lmd_ghost.html\nConsensus: LMD-GHOST]
    C --> G[book/metrics.html\nOperations: Metrics]
    C --> H[book/checkpoint_sync.html\nOperations: Checkpoint Sync]
    C --> I[book/fork_choice_visualization.html\nOperations: Fork Choice Viz]
    C --> J[book/infographics/\n*.html copied verbatim]
    A2[make docs-serve\nmdbook serve --open] --> K[Live-reload preview\nlocalhost:3000]
    style C fill:#f0f4ff,stroke:#4a6fa5

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: Makefile
Line: 51

Comment:
**Consider adding `--locked` to the `cargo install` invocation**

Without `--locked`, Cargo resolves mdbook's transitive dependencies fresh on every install, which can produce a slightly different binary across developer machines even when the top-level version is pinned. Adding `--locked` forces Cargo to use the dependency versions recorded in mdbook's upstream `Cargo.lock`, making the installed tool fully reproducible.

```suggestion
	cargo install --locked --version 0.4.51 mdbook
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "docs: render documentation site with mdb..." | Re-trigger Greptile}

[greptile-apps]

Consider adding --locked to the cargo install invocation

Without --locked, Cargo resolves mdbook's transitive dependencies fresh on every install, which can produce a slightly different binary across developer machines even when the top-level version is pinned. Adding --locked forces Cargo to use the dependency versions recorded in mdbook's upstream Cargo.lock, making the installed tool fully reproducible.

Suggested change

	cargo install --locked --version 0.4.51 mdbook

Prompt To Fix With AI

This is a comment left during a code review.
Path: Makefile
Line: 51

Comment:
**Consider adding `--locked` to the `cargo install` invocation**

Without `--locked`, Cargo resolves mdbook's transitive dependencies fresh on every install, which can produce a slightly different binary across developer machines even when the top-level version is pinned. Adding `--locked` forces Cargo to use the dependency versions recorded in mdbook's upstream `Cargo.lock`, making the installed tool fully reproducible.

```suggestion
	cargo install --locked --version 0.4.51 mdbook
```

How can I resolve this? If you propose a fix, please make it concise.

[github-actions]

🤖 Codex Code Review

No correctness, security, or performance findings in the changed lines.

This PR is docs/build-only: it adds mdBook scaffolding and navigation, but it does not touch fork choice, attestation validation, justification/finalization, state transition, XMSS, or SSZ code paths. I also checked that the new links in docs/SUMMARY.md and docs/introduction.md point to files that exist under docs/.

Residual risk: I couldn’t run mdbook build or make docs in this environment because mdbook is not installed here, so the rendered book output itself wasn’t validated.

---

Automated review by OpenAI Codex · gpt-5.4 · custom prompt