mdbook gh-pages via nix build

[bc1cindy]

Supersedes #5, which GitHub auto-closed after the force push to main and refuses to reopen; branch is rebased onto the new main.

nix build renders the site into result/ (default package, flake-parts as in concurrent-psbt); graphviz, mermaid and katex all render at build time, footnotes are native. Deploys via artifact, no gh-pages branch.

nixpkgs 26.05 ships mdbook 0.5 alongside preprocessor releases that predate it, so nix/preprocessors.nix builds the upstream versions that added 0.5 support (drop that file once nixpkgs catches up)

per review: SUMMARY.md starts empty and chapters come in the other PRs; the last commit points the book at the top-level README ({{#include}}, no duplication)
closes #4

[bc1cindy]

[yuval-block]

one additional thing we might want to consider is mdbook-jupyter for #14 to be rendered in the mdbook display

i think that can be done in a followup PR or as part of #14, and we can merge this one so all the open PRs can already add their SUMMARY.md sections

[yuval-block]

(and i should mention that i believe all my feedback from #5 has been addressed, but i still need to re-review)

[bc1cindy]

#14 to be rendered in the mdbook display

done #14 (review)

(and i should mention that i believe all my feedback from #5 has been addressed)

yup, all addressed

[arminsabouri]

tACK c749173
Tested the following:

• dev shell with nix develop
• Served mdbooks
• Added mermiad diagram. Rendered fine.

Getting this one warning when building

2026-08-07T13:57:48.217612Z  WARN mdbook_katex: This mdbook-katex was built against mdbook v0.5.3, but we are being called from mdbook v0.5.2. If you have any issue, this might be a reason.

math however is not rendering on the refrenced markdown files. Only the ones in src/

[arminsabouri]

what is "supports"?

[bc1cindy]

this is part of mdbook's preprocessor protocol, mdbook invokes the preprocessor as supports to ask if it supports that renderer (exit 0 = yes) before piping the book JSON

https://rust-lang.github.io/mdBook/for_developers/preprocessors.html

[arminsabouri]

The issue is the ordering of the preprocessors. Link needs to run first. (not sure why mermaid diagrams did not have the same issue)

This change in book.toml ended up fixing it for me.

 [preprocessor.graphviz]
 command = "mdbook-graphviz"
+after = ["links"]

 [preprocessor.mermaid]
 command = "python3 contrib/mermaid_ssr.py"
+after = ["links", "graphviz"]

 [preprocessor.katex]
 command = "mdbook-katex"
+after = ["links"]

7a485db

[bc1cindy]

The issue is the ordering of the preprocessors. Link needs to run first. (not sure why mermaid diagrams did not have the same issue)

nice catch! thank you Armin!

just cherry-picked and github is showing "Recent push is being processed and will appear soon"

so guess it will appear soon

[bc1cindy]

superseed by #23 because of gh issues