Distribute and run LLMs with a single file.
C++ cross-platformggufllama-cpplocal-ailocal-inferencelocal-llmopen-source-aisingle-file-executablespeech-to-text
Migrate docs from MkDocs/GitHub Pages to GitBook (#946)
angptcb2a9b450156
diff --git a/.gitbook-branch-readme.md b/.gitbook-branch-readme.mdnew file mode 100644index 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.yamlnew file mode 100644index 00000000..ad539865--- /dev/null+++ b/.gitbook.yaml@@ -0,0 +1,5 @@+root: ./docs++structure:+ readme: index.md+ summary: SUMMARY.mddiff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlindex 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-lateststeps:- name: Check out the repository- uses: actions/checkout@v5+ uses: actions/checkout@v4with: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+ fidiff --git a/.gitignore b/.gitignoreindex 356ba3f3..f6bb268f 100644--- a/.gitignore+++ b/.gitignore@@ -20,3 +20,6 @@ CLAUDE.md*.pyc__init__.pyuv.lock++# docs build output (pushed to gitbook-docs branch by CI)+/site\ No newline at end of filediff --git a/README.md b/README.mdindex 4c64f8eb..6b41c22c 100644--- a/README.md+++ b/README.md@@ -58,7 +58,7 @@ chmod +x Qwen3.5-0.8B-Q8_0.llamafileWe chose this model because that's the smallest one we havebuilt 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 accurateresponses.@@ -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)## Licensingdiff --git a/README_0.10.0.md b/README_0.10.0.mdindex 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 moduleusing 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.mdnew file mode 100644index 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.mdindex 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 in03/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.mdindex 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 buildfrom 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 weightsalready 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 modelpath so it loads automatically).diff --git a/docs/source_installation.md b/docs/source_installation.mdindex 7ba9b797..6a63e8ec 100644--- a/docs/source_installation.md+++ b/docs/source_installation.md@@ -47,7 +47,7 @@ make checkThis 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 llamafilediff --git a/mkdocs.yml b/mkdocs.ymldeleted file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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())