Skip to content

Commit 1f6e2fa

Browse files
angptangpt
authored
docs: migrate from MkDocs/GitHub Pages to GitBook (#391)
Replaces the MkDocs + GitHub Pages docs pipeline with a GitBook-based one. - Source of truth stays in docs/ on main — no change to authoring workflow - scripts/convert_to_gitbook.py : copies docs/ → site/, converts MkDocs-specific syntax (admonitions, tabs, footnotes, file snippets) to GitBook-compatible markdown, and writes SUMMARY.md - .github/workflows/docs.yml now runs the script on push to main and rsyncs the output to an orphan gitbook-docs branch, which GitBook reads from - mkdocs.yml removed, along with the docs dep group from pyproject.toml (mkdocs, mkdocs-material, mkdocs-include-markdown-plugin) To test locally: python scripts/convert_to_gitbook.py — output lands in site/
1 parent 9cb0186 commit 1f6e2fa

20 files changed

Lines changed: 642 additions & 569 deletions

‎.gitbook-branch-readme.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# GitBook Documentation Branch
2+
3+
The `gitbook-docs` branch contains **generated** GitBook-compatible documentation,
4+
automatically updated by GitHub Actions on every push to `main`.
5+
6+
**Do not edit this branch manually** — all changes will be overwritten.
7+
8+
## How it works
9+
10+
1. `scripts/convert_to_gitbook.py` copies `docs/` into `site/`, converts
11+
MkDocs-specific syntax (snippets, admonitions, tabs, footnotes) to
12+
GitBook-compatible Markdown, and writes `SUMMARY.md`
13+
2. The contents of `site/` are pushed to this branch
14+
3. GitBook syncs from this branch

‎.gitbook.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
root: ./
2+
3+
structure:
4+
readme: index.md
5+
summary: SUMMARY.md

‎.github/workflows/docs.yml‎

Lines changed: 54 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,71 @@
1-
name: docs
1+
name: Documentation
22

33
on:
44
push:
5-
tags:
6-
- "v*.*.*"
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- "scripts/prepare_gitbook_site.py"
9+
- "scripts/check_docs.py"
10+
- ".gitbook.yaml"
11+
- "Justfile"
12+
- ".github/workflows/docs.yml"
13+
pull_request:
14+
paths:
15+
- "docs/**"
16+
- "scripts/prepare_gitbook_site.py"
17+
- "scripts/check_docs.py"
18+
- ".gitbook.yaml"
19+
- "Justfile"
20+
- ".github/workflows/docs.yml"
721
workflow_dispatch:
822

9-
permissions:
10-
contents: write
11-
1223
jobs:
13-
deploy:
24+
docs:
25+
permissions:
26+
contents: write
1427
runs-on: ubuntu-latest
1528
steps:
16-
- uses: actions/checkout@v4
29+
- name: Check out the repository
30+
uses: actions/checkout@v4
1731
with:
18-
fetch-depth: 0 # <-- required so tags + full history are present
19-
20-
- name: Configure Git Credentials
21-
run: |
22-
git config user.name github-actions[bot]
23-
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
32+
fetch-depth: 0
2433

2534
- uses: actions/setup-python@v5
2635
with:
27-
python-version: 3.x
36+
python-version: "3.13"
2837

29-
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
30-
- uses: actions/cache@v4
31-
with:
32-
key: mkdocs-material-${{ env.cache_id }}
33-
path: ~/.cache
38+
- name: Install uv
39+
run: python -m pip install uv
3440

35-
restore-keys: |
36-
mkdocs-material-
41+
- name: Sync Python dependencies
42+
run: uv sync --locked
3743

38-
- name: Install dependencies
39-
run: |
40-
pip install uv
44+
- name: Check documentation links
45+
run: uv run python scripts/check_docs.py
4146

42-
- name: Build & Deploy
47+
- name: Build GitBook site
48+
run: uv run python scripts/prepare_gitbook_site.py
49+
50+
- name: Deploy to gitbook-docs branch
51+
if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
4352
run: |
44-
uv run --group docs mkdocs gh-deploy --force
53+
git config user.name 'github-actions[bot]'
54+
git config user.email 'github-actions[bot]@users.noreply.github.com'
55+
56+
mv site/ /tmp/gitbook-site/
57+
58+
git fetch origin gitbook-docs || true
59+
if git rev-parse --verify origin/gitbook-docs >/dev/null 2>&1; then
60+
git checkout gitbook-docs
61+
else
62+
git checkout --orphan gitbook-docs
63+
git rm -rf .
64+
fi
65+
66+
rsync -a --delete --exclude='.git' /tmp/gitbook-site/ .
67+
git add -A
68+
if ! git diff --cached --quiet; then
69+
git commit -m "docs: update GitBook documentation from ${{ github.sha }}"
70+
git push origin gitbook-docs
71+
fi

‎Justfile‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,13 @@ build-py:
99
-m encoderfile-py/Cargo.toml
1010

1111
# Docs
12-
docs:
13-
@uv run --group docs -m mkdocs serve
12+
docs: docs-check docs-build
13+
14+
docs-build:
15+
@uv run python scripts/prepare_gitbook_site.py
16+
17+
docs-check:
18+
@uv run python scripts/check_docs.py
1419

1520
# Check, Test, & Coverage
1621

‎README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,15 @@ Encoderfiles can run as:
5252

5353
<p align="center">
5454
<picture>
55-
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/encoderfile-dark.svg">
56-
<source media="(prefers-color-scheme: light)" srcset="docs/assets/encoderfile-light.svg">
57-
<img alt="Architecture Diagram" src="docs/assets/encoderfile-light.svg" width="80%">
55+
<source
56+
srcset="docs/assets/encoderfile-dark.svg"
57+
media="(prefers-color-scheme: dark)"
58+
/>
59+
<img
60+
src="docs/assets/encoderfile-light.svg"
61+
alt="Architecture Diagram"
62+
width="80%"
63+
/>
5864
</picture>
5965
</p>
6066

‎docs/CODE_OF_CONDUCT.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1-
--8<-- "CODE_OF_CONDUCT.md"
1+
# Code of Conduct
2+
3+
The canonical code of conduct lives at the repository root in [../CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md).
4+
5+
The GitBook packaging step copies that canonical file into the published site so the rendered docs stay in sync without maintaining a second copy here.

‎docs/CONTRIBUTING.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1-
--8<-- "CONTRIBUTING.md"
1+
# Contributing
2+
3+
The canonical contributing guide lives at the repository root in [../CONTRIBUTING.md](../CONTRIBUTING.md).
4+
5+
The GitBook packaging step copies that canonical file into the published site so the rendered docs stay in sync without maintaining a second copy here.

‎docs/SUMMARY.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Table of Contents
2+
3+
* [Introduction](index.md)
4+
* [Getting Started](getting-started.md)
5+
6+
## Building Encoderfiles
7+
8+
* [Building with Docker](building_encoderfiles/docker.md)
9+
10+
## Python Library
11+
12+
* [Building with Python](python/building-with-python.md)
13+
* [API Reference](python/api-reference.md)
14+
15+
## Cookbooks
16+
17+
* [Token Classification (NER)](cookbooks/token-classification-ner.md)
18+
* [MCP Integration](cookbooks/mcp-integration.md)
19+
* [Matryoshka Embeddings](cookbooks/matryoshka-embeddings.md)
20+
* [Local RAG](cookbooks/local-rag.md)
21+
* [CVE Semantic Search](cookbooks/qdrant-cve-search.md)
22+
23+
## Transforms
24+
25+
* [Transforms](transforms/index.md)
26+
* [Reference](transforms/reference.md)
27+
28+
## Reference
29+
30+
* [Encoderfile File Format](reference/file_format.md)
31+
* [CLI Reference](reference/cli.md)
32+
* [API Reference](reference/api-reference.md)
33+
* [Building Guide](reference/building.md)
34+
35+
## Community
36+
37+
* [Contributing](CONTRIBUTING.md)
38+
* [Code of Conduct](CODE_OF_CONDUCT.md)

‎docs/building_encoderfiles/docker.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,11 @@ You can pull the image from [our image registry](https://github.com/mozilla-ai/e
1010
docker pull ghcr.io/mozilla-ai/encoderfile:latest
1111
```
1212

13-
!!! note "Note on Architecture"
14-
Images are published for both `x86_64` and `arm64`. If you're on a more exotic architecture, you'll need to build the encoderfile CLI from source — see our guide on [Building from Source](../reference/building.md) for more details.
13+
{% hint style="info" %}
14+
**Note on Architecture**
15+
16+
Images are published for both `x86_64` and `arm64`. If you're on a more exotic architecture, you'll need to build the encoderfile CLI from source - see our guide on [Building from Source](../reference/building.md) for more details.
17+
{% endhint %}
1518

1619
## Mounting Assets
1720

0 commit comments

Comments
 (0)