Migrate docs from MkDocs/GitHub Pages to GitBook (#946)

angpt · claude · web-flow · commit cb2a9b450156 · 2026-04-16T10:32:30.000-05:00
- Remove mkdocs.yml and the MkDocs GitHub Actions workflow
- Add .gitbook.yaml, docs/SUMMARY.md, and .gitbook-branch-readme.md
- Add scripts/publish_docs.py: copies public docs/ into site/,
  excluding internal dirs (AGENTS.md, commands/, skills/)
- Add scripts/validate_docs.py: checks SUMMARY links and relative
  .md links resolve before deployment; runs on every PR
- Add CI workflow that builds, validates, and pushes site/ to an
  orphan gitbook-docs branch on push to main
- Replace 15 hardcoded mozilla-ai.github.io URLs with relative links
- Fix /tests/integration/README.md root-absolute path in
  source_installation.md to a full GitHub URL

Co-authored-by: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.gitbook-branch-readme.md b/.gitbook-branch-readme.md
@@ -0,0 +1,19 @@
+# GitBook Documentation Branch
+
+The `gitbook-docs` branch contains **published** GitBook-compatible documentation,
+automatically updated by GitHub Actions on every push to `main`.
+
+**Do not edit this branch manually** — all changes will be overwritten.
+
+## How it works
+
+1. `scripts/publish_docs.py` copies public docs from `docs/` into `site/`, excluding
+   internal developer docs (`AGENTS.md`, `commands/`, `skills/`)
+2. The contents of `site/` are pushed to this branch
+3. GitBook syncs from this branch
+
+## Editing docs
+
+Edit markdown files in [`docs/`](https://github.com/mozilla-ai/llamafile/tree/main/docs)
+on the `main` branch. The `gitbook-docs` branch will update automatically on the next
+push to `main` that touches `docs/`.
diff --git a/.gitbook.yaml b/.gitbook.yaml
@@ -0,0 +1,5 @@
+root: ./docs
+
+structure:
+  readme: index.md
+  summary: SUMMARY.md
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -4,13 +4,17 @@ on:
   push:
     branches: [main]
     paths:
-      - mkdocs.yml
       - 'docs/**'
+      - 'scripts/publish_docs.py'
+      - 'scripts/validate_docs.py'
+      - '.gitbook.yaml'
       - '.github/workflows/docs.yml'
   pull_request:
     paths:
-      - mkdocs.yml
       - 'docs/**'
+      - 'scripts/publish_docs.py'
+      - 'scripts/validate_docs.py'
+      - '.gitbook.yaml'
       - '.github/workflows/docs.yml'
   workflow_dispatch:
 
@@ -21,28 +25,37 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.x'
+      - name: Build GitBook site
+        run: python scripts/publish_docs.py
+
+      - name: Validate site output
+        run: python scripts/validate_docs.py
 
-      - name: Configure git
+      - name: Deploy to gitbook-docs branch
+        if: "${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}"
         run: |
           git config user.name 'github-actions[bot]'
           git config user.email 'github-actions[bot]@users.noreply.github.com'
+          cp .gitbook-branch-readme.md site/README-BRANCH.md
 
-      - name: Install dependencies
-        run: |
-          pip install mkdocs-material
+          # Move site/ outside the repo before switching branches
+          mv site/ /tmp/gitbook-site/
 
-      - name: Build docs
-        if: github.event_name == 'pull_request'
-        run: mkdocs build -s
+          git fetch origin gitbook-docs || true
+          if git rev-parse --verify origin/gitbook-docs >/dev/null 2>&1; then
+            git checkout gitbook-docs
+          else
+            git checkout --orphan gitbook-docs
+            git rm -rf .
+          fi
 
-      - name: Publish docs
-        if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
-        run: mkdocs gh-deploy --force
+          rsync -a --delete --exclude='.git' /tmp/gitbook-site/ .
+          git add -A
+          if ! git diff --cached --quiet; then
+            git commit -m "docs: update GitBook documentation from ${{ github.sha }}"
+            git push origin gitbook-docs
+          fi
diff --git a/.gitignore b/.gitignore
@@ -20,3 +20,6 @@ CLAUDE.md
 *.pyc
 __init__.py
 uv.lock
+
+# docs build output (pushed to gitbook-docs branch by CI)
+/site
diff --git a/README.md b/README.md
@@ -58,25 +58,25 @@ chmod +x Qwen3.5-0.8B-Q8_0.llamafile
 
 We chose this model because that's the smallest one we have
 built a llamafile for, so most likely to work out-of-the-box for you.
-If you have powerful hardware and/or GPUs, [feel free to choose](https://mozilla-ai.github.io/llamafile/example_llamafiles/)
+If you have powerful hardware and/or GPUs, [feel free to choose](docs/example_llamafiles.md)
 larger and more expressive models which should provide more accurate
 responses.
 
 **Windows users:** Rename the file to add `.exe` extension before running.
 
 ## Documentation
 
-Check the full documentation in the [docs/](docs/) folder or online at [mozilla-ai.github.io/llamafile](https://mozilla-ai.github.io/llamafile/), or directly jump into one of the following subsections:
-
-- [Quickstart](https://mozilla-ai.github.io/llamafile/quickstart/)
-- [Example llamafiles](https://mozilla-ai.github.io/llamafile/example_llamafiles/)
-- [Running a llamafile](https://mozilla-ai.github.io/llamafile/running_llamafile/)
-- [Creating llamafiles](https://mozilla-ai.github.io/llamafile/creating_llamafiles/)
-- [Source installation](https://mozilla-ai.github.io/llamafile/source_installation/)
-- [Technical details](https://mozilla-ai.github.io/llamafile/technical_details/)
-- [Supported Systems](https://mozilla-ai.github.io/llamafile/support/)
-- [Troubleshooting](https://mozilla-ai.github.io/llamafile/troubleshooting/)
-- [Whisperfile](https://mozilla-ai.github.io/llamafile/whisperfile/)
+Check the full documentation in the [docs/](docs/) folder, or directly jump into one of the following subsections:
+
+- [Quickstart](docs/quickstart.md)
+- [Example llamafiles](docs/example_llamafiles.md)
+- [Running a llamafile](docs/running_llamafile.md)
+- [Creating llamafiles](docs/creating_llamafiles.md)
+- [Source installation](docs/source_installation.md)
+- [Technical details](docs/technical_details.md)
+- [Supported Systems](docs/support.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Whisperfile](docs/whisperfile/index.md)
 
 
 ## Licensing
diff --git a/README_0.10.0.md b/README_0.10.0.md
@@ -53,7 +53,7 @@ mode) are new.
 [20251218](https://github.com/mozilla-ai/llamafile/discussions/845)
 - added Metal support: GPU on MacOS ARM64 is supported by compiling a small module
 using the Xcode Command Line Tools, which need to be installed. Check our docs at
-https://mozilla-ai.github.io/llamafile/support/#gpu-support for more info.
+[docs/support.md#gpu-support](docs/support.md#gpu-support) for more info.
 - Metal works both in llamafile (called either as TUI or with the --server flag)
 and in llama-server.
 
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -0,0 +1,30 @@
+# Table of contents
+
+* [Home](index.md)
+
+## Getting Started
+
+* [Quickstart](quickstart.md)
+* [Example llamafiles](example_llamafiles.md)
+
+## Using llamafile
+
+* [Running a llamafile](running_llamafile.md)
+* [Creating llamafiles](creating_llamafiles.md)
+* [Source installation](source_installation.md)
+* [Building DLLs](building_dlls.md)
+
+## Reference
+
+* [Technical details](technical_details.md)
+* [Supported Systems](support.md)
+* [Troubleshooting](troubleshooting.md)
+
+## Whisperfile
+
+* [Overview](whisperfile/index.md)
+* [Getting Started](whisperfile/getting-started.md)
+* [Packaging](whisperfile/packaging.md)
+* [Using GPUs](whisperfile/gpu.md)
+* [Translation](whisperfile/translate.md)
+* [Server](whisperfile/server.md)
diff --git a/docs/building_dlls.md b/docs/building_dlls.md
@@ -68,4 +68,4 @@ At the end of this process, you should have the following libraries available in
 03/31/2026  02:46 PM        31,482,880 ggml-vulkan.dll
 ```
 
-To run llamafile with these libraries, add them in your home directory or bundle them in your llamafile (see [Creating a llamafile](https://mozilla-ai.github.io/llamafile/creating_llamafiles/)).
+To run llamafile with these libraries, add them in your home directory or bundle them in your llamafile (see [Creating a llamafile](creating_llamafiles.md)).
diff --git a/docs/creating_llamafiles.md b/docs/creating_llamafiles.md
@@ -29,12 +29,12 @@ make o//third_party/zipalign
 - **The llamafile executable** — download a prebuilt binary from the
   [releases page](https://github.com/mozilla-ai/llamafile/releases), or build
   from source following
-  [these instructions](https://mozilla-ai.github.io/llamafile/source_installation/).
+  [these instructions](source_installation.md).
 
 - **Model weights in GGUF format** — download from Hugging Face
   ([search here](https://huggingface.co/models?library=gguf)), or use weights
   already on disk from
-  [another application](https://mozilla-ai.github.io/llamafile/quickstart/#running-llamafile-with-models-downloaded-by-third-party-applications).
+  [another application](quickstart.md#running-llamafile-with-models-downloaded-by-third-party-applications).
 
 - **A `.args` file** — specifies default arguments (at minimum, the model
   path so it loads automatically).
diff --git a/docs/source_installation.md b/docs/source_installation.md
@@ -47,7 +47,7 @@ make check
 This runs our unit tests to ensure everything is built correctly.
 
 Some integration tests in `tests/integration` are available to test llamafile
-with real models. Check the [README](/tests/integration/README.md) to learn how to run them. 
+with real models. Check the [README](https://github.com/mozilla-ai/llamafile/blob/main/tests/integration/README.md) to learn how to run them.
 
 ### Running llamafile
 
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/scripts/publish_docs.py b/scripts/publish_docs.py
@@ -0,0 +1,55 @@
+"""Build the GitBook site output into site/.
+
+Copies public docs into site/, excluding internal developer docs.
+The contents of site/ are pushed to the gitbook-docs branch by CI.
+
+Usage:
+    python scripts/publish_docs.py
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+DOCS_SRC = Path("docs")
+SITE_DIR = Path("site")
+
+# Internal developer docs — not published to GitBook
+EXCLUDE_PATHS = {
+    "AGENTS.md",
+    "commands",
+    "skills",
+}
+
+GITBOOK_YAML = """\
+root: ./
+
+structure:
+  readme: index.md
+  summary: SUMMARY.md
+"""
+
+
+def main() -> None:
+    if SITE_DIR.exists():
+        shutil.rmtree(SITE_DIR)
+    SITE_DIR.mkdir()
+
+    for src in DOCS_SRC.iterdir():
+        if src.name in EXCLUDE_PATHS:
+            continue
+        dst = SITE_DIR / src.name
+        if src.is_dir():
+            shutil.copytree(src, dst)
+        else:
+            shutil.copy2(src, dst)
+
+    (SITE_DIR / ".gitbook.yaml").write_text(GITBOOK_YAML, encoding="utf-8")
+
+    md_files = list(SITE_DIR.rglob("*.md"))
+    print(f"Done — {len(md_files)} markdown files written to {SITE_DIR}/")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/validate_docs.py b/scripts/validate_docs.py
