alexnodeland · alexnodeland · Feb 22, 2026 · Dec 13, 2025 · Dec 13, 2025 · Jan 7, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -122,6 +122,38 @@ jobs:
         env:
           RUSTDOCFLAGS: -Dwarnings
 
+  mdbook:
+    name: mdbook
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-mdbook-
+
+      - name: Install mdbook
+        run: |
+          mkdir -p $HOME/.local/bin
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.44/mdbook-v0.4.44-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C $HOME/.local/bin
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Build mdbook
+        run: mdbook build docs
+
+      - name: Test code examples in mdbook
+        run: mdbook test docs
+
   wasm:
     name: WASM Build
     runs-on: ubuntu-latest
@@ -159,7 +191,7 @@ jobs:
   # Summary job that depends on all other jobs
   ci-success:
     name: CI Success
-    needs: [check, fmt, clippy, test, doc, wasm]
+    needs: [check, fmt, clippy, test, doc, mdbook, wasm]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -170,6 +202,7 @@ jobs:
              [[ "${{ needs.clippy.result }}" != "success" ]] || \
              [[ "${{ needs.test.result }}" != "success" ]] || \
              [[ "${{ needs.doc.result }}" != "success" ]] || \
+             [[ "${{ needs.mdbook.result }}" != "success" ]] || \
              [[ "${{ needs.wasm.result }}" != "success" ]]; then
             echo "One or more jobs failed"
             exit 1

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,87 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install mdbook
+        run: |
+          mkdir -p $HOME/.local/bin
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.44/mdbook-v0.4.44-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C $HOME/.local/bin
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-docs-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-docs-
+
+      - name: Build rustdoc
+        run: cargo doc --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: --enable-index-page -Zunstable-options
+
+      - name: Build mdbook
+        run: mdbook build docs
+
+      - name: Combine documentation
+        run: |
+          # Copy rustdoc into mdbook output under /api
+          mkdir -p docs/book/api
+          cp -r target/doc/* docs/book/api/
+          # Create a redirect from api/index.html to the main crate
+          echo '<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=fugue_evo/index.html"></head><body>Redirecting to <a href="fugue_evo/index.html">fugue_evo</a>...</body></html>' > docs/book/api/index.html
+          # Copy CNAME for custom domain
+          cp docs/CNAME docs/book/CNAME
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/book
+
+  deploy:
+    name: Deploy to GitHub Pages
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -10,3 +10,4 @@
 # OS
 .DS_Store
 Thumbs.db
+docs/book/
diff --git a/Makefile b/Makefile
@@ -1,4 +1,5 @@
-.PHONY: all build check test lint fmt clippy doc clean ci help
+.PHONY: all build check test lint fmt clippy doc clean ci help \
+       mdbook mdbook-serve mdbook-clean mdbook-test doc-all doc-serve clean-all
 
 # Default target
 all: check
@@ -47,12 +48,45 @@ doc:
 doc-open:
 	cargo doc --no-deps --all-features --open
 
+# Build mdbook documentation
+mdbook:
+	mdbook build docs
+
+# Serve mdbook documentation locally with live reload
+mdbook-serve:
+	mdbook serve docs --open
+
+# Clean mdbook build artifacts
+mdbook-clean:
+	rm -rf docs/book
+
+# Test code examples in mdbook documentation
+mdbook-test:
+	mdbook test docs
+
+# Build all documentation (rustdoc + mdbook)
+doc-all: doc mdbook
+	@echo "All documentation built successfully!"
+
+# Serve all documentation (copies rustdoc into mdbook output)
+doc-serve: doc mdbook
+	@mkdir -p docs/book/api
+	@cp -r target/doc/* docs/book/api/
+	@echo "Documentation available at docs/book/"
+	@echo "  - Guide: docs/book/index.html"
+	@echo "  - API:   docs/book/api/fugue_evo/index.html"
+	mdbook serve docs --open
+
 # Clean build artifacts
 clean:
 	cargo clean
 
+# Clean all build artifacts (cargo + mdbook)
+clean-all: clean mdbook-clean
+	@echo "All build artifacts cleaned!"
+
 # Run the full CI pipeline (same as GitHub Actions)
-ci: fmt clippy check test doc
+ci: fmt clippy check test doc mdbook
 	@echo "CI pipeline completed successfully!"
 
 # Run quick checks (for development)
@@ -92,9 +126,16 @@ help:
 	@echo "  fmt-fix      - Fix code formatting"
 	@echo "  clippy       - Run clippy linter"
 	@echo "  clippy-fix   - Run clippy and apply fixes"
-	@echo "  doc          - Generate documentation"
-	@echo "  doc-open     - Generate and open documentation"
-	@echo "  clean        - Clean build artifacts"
+	@echo "  doc          - Generate rustdoc documentation"
+	@echo "  doc-open     - Generate and open rustdoc"
+	@echo "  mdbook       - Build mdbook documentation"
+	@echo "  mdbook-serve - Serve mdbook with live reload"
+	@echo "  mdbook-clean - Clean mdbook build artifacts"
+	@echo "  mdbook-test  - Test code examples in mdbook"
+	@echo "  doc-all      - Build all documentation (rustdoc + mdbook)"
+	@echo "  doc-serve    - Build and serve all documentation"
+	@echo "  clean        - Clean cargo build artifacts"
+	@echo "  clean-all    - Clean all build artifacts (cargo + mdbook)"
 	@echo "  ci           - Run full CI pipeline"
 	@echo "  quick        - Run quick development checks"
 	@echo "  watch        - Watch for changes and run tests"

diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+evo.fugue.run
diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,34 @@
+[book]
+title = "Fugue-Evo Documentation"
+authors = ["Fugue-Evo Contributors"]
+language = "en"
+src = "src"
+
+[build]
+build-dir = "book"
+create-missing = true
+
+[output.html]
+default-theme = "rust"
+preferred-dark-theme = "ayu"
+git-repository-url = "https://github.com/alexnodeland/fugue-evo"
+edit-url-template = "https://github.com/alexnodeland/fugue-evo/edit/main/docs/{path}"
+site-url = "https://evo.fugue.run/"
+
+[output.html.playground]
+editable = true
+line-numbers = true
+
+[output.html.code]
+hidelines = { rust = "#" }
+
+[output.html.fold]
+enable = true
+level = 0
+
+[output.html.search]
+enable = true
+limit-results = 30
+teaser-word-count = 30
+
+[preprocessor.links]
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -0,0 +1,64 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+# Getting Started
+
+- [Installation](./getting-started/installation.md)
+- [Core Concepts](./getting-started/concepts.md)
+- [Quick Start](./getting-started/quickstart.md)
+- [Your First Optimization](./getting-started/first-optimization.md)
+
+# Tutorials
+
+- [Continuous Optimization](./tutorials/continuous-optimization.md)
+- [Multimodal Optimization](./tutorials/multimodal-optimization.md)
+- [Advanced Algorithms](./tutorials/advanced-algorithms.md)
+  - [CMA-ES](./tutorials/cmaes.md)
+  - [Island Model](./tutorials/island-model.md)
+- [Genetic Programming](./tutorials/genetic-programming.md)
+- [Interactive Evolution](./tutorials/interactive-evolution.md)
+- [Hyperparameter Learning](./tutorials/hyperparameter-learning.md)
+
+# How-To Guides
+
+- [Choosing an Algorithm](./how-to/choosing-algorithm.md)
+- [Custom Fitness Functions](./how-to/custom-fitness.md)
+- [Custom Genome Types](./how-to/custom-genome.md)
+- [Custom Operators](./how-to/custom-operators.md)
+- [Checkpointing & Recovery](./how-to/checkpointing.md)
+- [Parallel Evolution](./how-to/parallel-evolution.md)
+- [Multi-Objective Optimization](./how-to/multi-objective.md)
+- [WASM & Browser Usage](./how-to/wasm.md)
+
+# Reference
+
+- [Algorithms](./reference/algorithms.md)
+  - [SimpleGA](./reference/algorithms/simple-ga.md)
+  - [CMA-ES](./reference/algorithms/cmaes.md)
+  - [NSGA-II](./reference/algorithms/nsga2.md)
+  - [Island Model](./reference/algorithms/island-model.md)
+  - [EDA/UMDA](./reference/algorithms/eda.md)
+- [Genome Types](./reference/genomes.md)
+  - [RealVector](./reference/genomes/real-vector.md)
+  - [BitString](./reference/genomes/bit-string.md)
+  - [Permutation](./reference/genomes/permutation.md)
+  - [TreeGenome](./reference/genomes/tree-genome.md)
+- [Operators](./reference/operators.md)
+  - [Selection](./reference/operators/selection.md)
+  - [Crossover](./reference/operators/crossover.md)
+  - [Mutation](./reference/operators/mutation.md)
+- [Fitness Functions](./reference/fitness.md)
+- [Termination Criteria](./reference/termination.md)
+
+# Architecture
+
+- [Design Philosophy](./architecture/philosophy.md)
+- [Fugue Integration](./architecture/fugue-integration.md)
+- [Type System](./architecture/type-system.md)
+
+-----------
+
+[API Documentation](./api-docs.md)
+[Contributing](./contributing.md)
+[Changelog](./changelog.md)