Skip to content

Distribute and run LLMs with a single file.

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

angptcb2a9b450156
diff --git a/.gitbook-branch-readme.md b/.gitbook-branch-readme.md
new file mode 100644
index 00000000..8b9c7f81
--- /dev/null
+++ 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
new file mode 100644
index 00000000..ad539865
--- /dev/null
+++ 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
index 454621a8..eebaf2e4 100644
--- 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
index 356ba3f3..f6bb268f 100644
--- 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
\ No newline at end of file
diff --git a/README.md b/README.md
index 4c64f8eb..6b41c22c 100644
--- a/README.md
+++ b/README.md
@@ -58,7 +58,7 @@ 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.
@@ -66,17 +66,17 @@ responses.
## 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
index 5c486029..e81c5563 100644
--- 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
new file mode 100644
index 00000000..c88d0c60
--- /dev/null
+++ 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
index 1f8dabf1..5baf3eba 100644
--- 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
index c9215c3e..1707fb8a 100644
--- 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
index 7ba9b797..6a63e8ec 100644
--- 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
deleted file mode 100644
index 3b824995..00000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,71 +0,0 @@
-site_name: llamafile
-
-repo_url: https://github.com/mozilla-ai/llamafile
-repo_name: llamafile
-
-nav:
- - Home: index.md
- - Quickstart: quickstart.md
- - Example llamafiles: example_llamafiles.md
- - Running a llamafile: running_llamafile.md
- - Creating llamafiles: creating_llamafiles.md
- - Source installation: source_installation.md
- - Building DLLs: building_dlls.md
- - 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
-
-theme:
- name: material
- font:
- text: Noto Sans
- code: Noto Sans Mono
- palette:
- - media: "(prefers-color-scheme: light)"
- scheme: default
- primary: blue grey
- toggle:
- icon: material/lightbulb
- name: Switch to dark mode
- - media: "(prefers-color-scheme: dark)"
- scheme: slate
- primary: grey
- toggle:
- icon: material/lightbulb-outline
- name: Switch to light mode
- - accent: blue
- logo: images/llamafile-640x640.png
- favicon: images/llamafile-640x640.png
- features:
- - content.code.copy
- - content.tabs.link
- - content.action.edit
- - navigation.expand
- - navigation.footer
- - navigation.sections
-
-markdown_extensions:
- - admonition
- - pymdownx.highlight:
- anchor_linenums: true
- line_spans: __span
- pygments_lang_class: true
- - pymdownx.inlinehilite
- - pymdownx.snippets
- - pymdownx.superfences
- - pymdownx.tabbed:
- alternate_style: true
- - attr_list
- - md_in_html
-
-plugins:
- - search
-
-edit_uri: edit/main/docs/
diff --git a/scripts/publish_docs.py b/scripts/publish_docs.py
new file mode 100644
index 00000000..31b82abd
--- /dev/null
+++ 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
new file mode 100644
index 00000000..c5282c5c
--- /dev/null
+++ b/scripts/validate_docs.py
@@ -0,0 +1,140 @@
+"""Validate the GitBook site/ output before deployment.
+
+Checks:
+ 1. site/.gitbook.yaml exists and contains required keys
+ 2. Every file linked in site/SUMMARY.md exists on disk
+ 3. Every relative .md link inside site/**/*.md resolves to a real file
+
+Exits non-zero on any failure so CI catches problems before deployment.
+
+Usage:
+ python scripts/validate_docs.py
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+SITE = Path("site")
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def error(msg: str) -> None:
+ print(f" ERROR {msg}", file=sys.stderr)
+
+
+def ok(msg: str) -> None:
+ print(f" ok {msg}")
+
+
+# ── 1. .gitbook.yaml ─────────────────────────────────────────────────────────
+
+def check_gitbook_yaml() -> list[str]:
+ failures: list[str] = []
+ path = SITE / ".gitbook.yaml"
+ if not path.exists():
+ failures.append("site/.gitbook.yaml is missing")
+ return failures
+
+ try:
+ import yaml # type: ignore[import]
+ cfg = yaml.safe_load(path.read_text())
+ except Exception:
+ # yaml not installed — parse minimally by hand
+ text = path.read_text()
+ cfg = {}
+ for line in text.splitlines():
+ if ":" in line and not line.startswith(" "):
+ k, _, v = line.partition(":")
+ cfg[k.strip()] = v.strip()
+
+ if "root" not in cfg:
+ failures.append("site/.gitbook.yaml: missing 'root' key")
+ else:
+ ok(".gitbook.yaml has 'root'")
+
+ return failures
+
+
+# ── 2. SUMMARY.md links ───────────────────────────────────────────────────────
+
+_SUMMARY_LINK = re.compile(r"\]\(([^)#]+\.md)(?:#[^)]*)?\)")
+
+
+def check_summary() -> list[str]:
+ failures: list[str] = []
+ summary = SITE / "SUMMARY.md"
+ if not summary.exists():
+ failures.append("site/SUMMARY.md is missing")
+ return failures
+
+ text = summary.read_text()
+ linked: list[str] = _SUMMARY_LINK.findall(text)
+ if not linked:
+ failures.append("SUMMARY.md: no markdown links found — is it empty?")
+ return failures
+
+ for rel in linked:
+ target = SITE / rel
+ if target.exists():
+ ok(f"SUMMARY -> {rel}")
+ else:
+ failures.append(f"SUMMARY.md links to missing file: {rel}")
+
+ return failures
+
+
+# ── 3. Relative links inside markdown files ───────────────────────────────────
+
+_MD_LINK = re.compile(r"\]\(([^)#:]+\.md)(?:#[^)]*)?\)")
+
+
+def check_relative_links() -> list[str]:
+ failures: list[str] = []
+ md_files = [p for p in SITE.rglob("*.md") if p.name != "SUMMARY.md"]
+
+ for md_file in sorted(md_files):
+ text = md_file.read_text()
+ for m in _MD_LINK.finditer(text):
+ rel = m.group(1)
+ # Resolve relative to the file's directory
+ target = (md_file.parent / rel).resolve()
+ site_abs = SITE.resolve()
+ if not str(target).startswith(str(site_abs)):
+ failures.append(f"{md_file.relative_to(SITE)}: link escapes site/: {rel}")
+ elif target.exists():
+ ok(f"{md_file.relative_to(SITE)} -> {rel}")
+ else:
+ failures.append(f"{md_file.relative_to(SITE)}: broken link -> {rel}")
+
+ return failures
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+
+def main() -> int:
+ if not SITE.exists():
+ print("ERROR: site/ directory not found — run publish_docs.py first", file=sys.stderr)
+ return 1
+
+ print("Validating site/ ...")
+ failures: list[str] = []
+ failures += check_gitbook_yaml()
+ failures += check_summary()
+ failures += check_relative_links()
+
+ print()
+ if failures:
+ print(f"FAILED — {len(failures)} issue(s):", file=sys.stderr)
+ for f in failures:
+ error(f)
+ return 1
+
+ print(f"All checks passed.")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())