11 files changed, 46 insertions, 96 deletions
diff --git a/tvix/docs/.gitignore b/tvix/docs/.gitignore
index 77699ee8a3f7..8117055463aa 100644
--- a/tvix/docs/.gitignore
+++ b/tvix/docs/.gitignore
@@ -1,2 +1,2 @@
-*.svg
-*.html
+book
+.mdbook-plantuml-cache/
diff --git a/tvix/docs/Makefile b/tvix/docs/Makefile
deleted file mode 100644
index ba9e2bdef6d3..000000000000
--- a/tvix/docs/Makefile
+++ /dev/null
@@ -1,12 +0,0 @@
-all: build
-
-puml:
-	plantuml *.puml -tsvg
-
-html:
-	pandoc *.md -f markdown --self-contained -t html -s -o tvix.html --csl=${CSL}
-
-build: puml html
-
-clean:
-	rm -f *.tex *.pdf *.png *.svg
diff --git a/tvix/docs/book.toml b/tvix/docs/book.toml
new file mode 100644
index 000000000000..7318a9023348
--- /dev/null
+++ b/tvix/docs/book.toml
@@ -0,0 +1,11 @@
+[book]
+authors = ["The Tvix Authors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Tvix Docs"
+
+[preprocessor.plantuml]
+# override the /usr/bin/plantuml default
+plantuml-cmd = "plantuml"
+use-data-uris = true
diff --git a/tvix/docs/default.nix b/tvix/docs/default.nix
index 016d641df59f..9fc2f765767a 100644
--- a/tvix/docs/default.nix
+++ b/tvix/docs/default.nix
@@ -1,47 +1,23 @@
 { pkgs, lib, ... }:
 
-let
-
-  tl = pkgs.texlive.combine {
-    inherit (pkgs.texlive) scheme-medium wrapfig ulem capt-of
-      titlesec preprint enumitem paralist ctex environ svg
-      beamer trimspaces zhnumber changepage framed pdfpages
-      fvextra minted upquote ifplatform xstring;
-  };
-
-  csl = pkgs.fetchurl {
-    name = "numeric.csl";
-    url = "https://gist.githubusercontent.com/bwiernik/8c6f39cf51ceb3a03107/raw/1d75c2d62113ffbba6ed03a47ad99bde86934f2b/APA%2520Numeric";
-    sha256 = "1yfhhnhbzvhrv93baz98frmgsx5y442nzhb0l956l4j35fb0cc3h";
-  };
-
-in
 pkgs.stdenv.mkDerivation {
-  pname = "tvix-doc";
+  pname = "tvix-docs";
   version = "0.1";
 
-  outputs = [ "out" "svg" ];
+  outputs = [ "out" ];
 
   src = lib.cleanSource ./.;
 
-  CSL = csl;
-
   nativeBuildInputs = [
-    pkgs.pandoc
+    pkgs.mdbook
+    pkgs.mdbook-plantuml
     pkgs.plantuml
-    tl
   ];
 
-  installPhase = ''
-    runHook preInstall
-
-    mkdir -p $out
-    cp -v *.html $out/
-
-    mkdir -p $svg
-    cp -v *.svg $svg/
-
-    runHook postSubmit
+  # plantuml wants to create ./.mdbook-plantuml-cache, which fails as $src is r/o.
+  # copy all sources elsewhere to workaround.
+  buildCommand = ''
+    cp -R $src/. .
+    mdbook build -d $out
   '';
-
 }
diff --git a/tvix/docs/src/SUMMARY.md b/tvix/docs/src/SUMMARY.md
new file mode 100644
index 000000000000..d4585c00acdf
--- /dev/null
+++ b/tvix/docs/src/SUMMARY.md
@@ -0,0 +1,10 @@
+# Summary
+
+# Tvix
+- [Architecture & data flow](./architecture.md)
+- [.drvPath inconsistencies](./differences-drv-paths.md)
+
+# Nix
+- [Specification of the Nix Language](./language-spec.md)
+- [Nix language version history](./lang-version.md)
+- [Value Pointer Equality](./value-pointer-equality.md)
diff --git a/tvix/docs/components.md b/tvix/docs/src/architecture.md
index a7d61948c2fa..5e0aa95f1a08 100644
--- a/tvix/docs/components.md
+++ b/tvix/docs/src/architecture.md
@@ -1,21 +1,6 @@
----
-title: "Tvix - Architecture & data flow"
-numbersections: true
-author:
-- adisbladis
-- flokli
-- tazjin
-email:
-- adis@blad.is
-- mail@tazj.in
-lang: en-GB
-classoption:
-- twocolumn
-header-includes:
-- \usepackage{caption, graphicx, tikz, aeguill, pdflscape}
----
-
-# Background
+# Tvix - Architecture & data flow
+
+## Background
 
 We intend for Tvix tooling to be more decoupled than the existing,
 monolithic Nix implementation. In practice, we expect to gain several
@@ -32,9 +17,9 @@ benefits from this, such as:
 Communication between different components of the system will use
 gRPC. The rest of this document outlines the components.
 
-# Components
+## Components
 
-## Coordinator
+### Coordinator
 
 *Purpose:* The coordinator (in the simplest case, the Tvix CLI tool)
 oversees the flow of a build process and delegates tasks to the right
@@ -52,7 +37,7 @@ coordinator on top of a state-machine model that would make it
 possible to reuse the FSM logic without tying it to any particular
 kind of application.
 
-## Evaluator
+### Evaluator
 
 *Purpose:* Eval takes care of evaluating Nix code. In a typical build
 flow it would be responsible for producing derivations. It can also be
@@ -72,7 +57,7 @@ accessible by the evaluator (this could be a FUSE filesystem, or the "real"
 We might be okay with running the evaluator with filesystem access for now and
 can extend the interface if the need arises.
 
-## Builder
+### Builder
 
 *Purpose:* A builder receives derivations from the coordinator and
 builds them.
@@ -106,7 +91,7 @@ derivations to that format). [^1]
 To build, the builder needs to be able to mount all build inputs into the build
 environment. For this, it needs the store to expose a filesystem interface.
 
-## Store
+### Store
 
 *Purpose:* Store takes care of storing build results. It provides a
 unified interface to get store paths and upload new ones, as well as querying
@@ -151,9 +136,11 @@ interface, exposing a lazily-substituting /nix/store mountpoint. Using this in
 remote build context dramatically reduces the amount of data transferred to a
 builder, as only the files really accessed during the build are substituted.
 
-# Figures
+## Figures
 
-![component flow](./component-flow.svg)
+```plantuml,format=svg
+{{#include figures/component-flow.puml}}
+```
 
 [^1]: There have already been some discussions in the Nix community, to switch
   to REAPI:
diff --git a/tvix/docs/differences-drv-paths.md b/tvix/docs/src/differences-drv-paths.md
index e93131aa57e2..f1c90bd52892 100644
--- a/tvix/docs/differences-drv-paths.md
+++ b/tvix/docs/src/differences-drv-paths.md
@@ -1,15 +1,4 @@
----
-title: ".drvPath inconsistencies"
-author:
- - tazjin
- - flokli
-email:
- - tazjin@tvl.su
- - flokli@flokli.de
-lang: en-GB
----
-
-# Why .drvPath differs between Nix and Tvix
+# .drvPath inconsistencies / Why .drvPath differs between Nix and Tvix
 
 Nix and Tvix currently use a different approach when it comes to tracking input
 references, in order to build the right dependencies in advance.
diff --git a/tvix/docs/component-flow.puml b/tvix/docs/src/figures/component-flow.puml
index 5b6d79b82313..5b6d79b82313 100644
--- a/tvix/docs/component-flow.puml
+++ b/tvix/docs/src/figures/component-flow.puml
diff --git a/tvix/docs/lang-version.md b/tvix/docs/src/lang-version.md
index c288274c9105..c288274c9105 100644
--- a/tvix/docs/lang-version.md
+++ b/tvix/docs/src/lang-version.md
diff --git a/tvix/docs/language-spec.md b/tvix/docs/src/language-spec.md
index a71437493307..0ff1dc491e3c 100644
--- a/tvix/docs/language-spec.md
+++ b/tvix/docs/src/language-spec.md
@@ -1,15 +1,4 @@
----
-title: "Specification of the Nix language"
-numbersections: true
-author:
-- tazjin
-email:
-- tazjin@tvl.su
-lang: en-GB
----
-
-The Nix Language
-================
+# Specification of the Nix Language
 
 WARNING: This document is a work in progress. Please keep an eye on
 [`topic:nix-spec`](https://cl.tvl.fyi/q/topic:nix-spec) for ongoing
diff --git a/tvix/docs/value-pointer-equality.md b/tvix/docs/src/value-pointer-equality.md
index d84efcb50ca9..d84efcb50ca9 100644
--- a/tvix/docs/value-pointer-equality.md
+++ b/tvix/docs/src/value-pointer-equality.md