# How the AI Agent Book MkDocs Site Is Built and Deployed: Complete Pipeline Guide

> Discover the three stage pipeline for building and deploying the AI Agent Book MkDocs site. Learn how documentation is assembled, rendered with MkDocs Material, and deployed to GitHub Pages.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: how-to-guide
- Published: 2026-08-24

---

**The AI Agent Book's MkDocs site is built via a three-stage pipeline that assembles documentation into a `_web/` directory using [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh), renders it with MkDocs Material configured in [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml), and deploys automatically to GitHub Pages via [`.github/workflows/deploy-pages.yml`](https://github.com/bojieli/ai-agent-book/blob/main/.github/workflows/deploy-pages.yml) on every push to the `main` branch.**

The `bojieli/ai-agent-book` repository contains a multilingual technical book about AI agents. Understanding how its **MkDocs site is built and deployed** reveals a sophisticated static site generation process that handles multiple language editions, chapter restructuring, and automated CI/CD while maintaining clean separation between source content and generated output.

## The Three-Stage Build Pipeline

The deployment process consists of distinct assembly, rendering, and deployment stages orchestrated by shell scripts and GitHub Actions.

### Stage 1: Assembling the Documentation Tree

The **assembly stage** prepares a clean documentation directory (`_web/`) that MkDocs will consume. This is handled by [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh), which performs several critical transformations:

- **Copies core content**: Root [`index.md`](https://github.com/bojieli/ai-agent-book/blob/main/index.md), language-specific homepages (`index.*.md`), and [`robots.txt`](https://github.com/bojieli/ai-agent-book/blob/main/robots.txt) are copied to the root of `_web/`.
- **Handles multilingual editions**: Each `book-<lang>` directory (including associated images) is copied to support multiple language versions.
- **Promotes chapter files**: For the default Chinese edition, the script converts flat chapter files ([`book/chapterN.md`](https://github.com/bojieli/ai-agent-book/blob/main/book/chapterN.md)) into directory indices ([`book/chapterN/index.md`](https://github.com/bojieli/ai-agent-book/blob/main/book/chapterN/index.md)) to support MkDocs URL schemes. This involves `sed`-based rewriting of relative image paths.
- **Includes experiment directories**: Runnable notebook directories (`chapterN/`) are copied verbatim to preserve executable examples.
- **Processes static assets**: The `extras/` directory (containing JavaScript/CSS for language switching, Mermaid diagrams, and MathJax) and `assets/` (logos and Open Graph images) are copied into the tree.
- **Cleans unwanted files**: The script invokes [`clean_site_files.py`](https://github.com/bojieli/ai-agent-book/blob/main/clean_site_files.py) to remove large data directories (such as law datasets), prune `node_modules`, and rewrite relative links in experiment READMEs to resolve correctly under the site's sub-path.

After execution, `_web/` contains a fully prepared documentation tree with all paths normalized for MkDocs consumption.

### Stage 2: Rendering with MkDocs Material

Once assembled, the `_web/` directory serves as the **`docs_dir`** specified in [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml). The rendering stage applies the Material theme and executes several custom hooks:

- **Theme configuration**: The [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml) file declares Material theme settings with SPA-style navigation (`navigation.instant`) and language tabbing capabilities.
- **Git revision date handling**: The [`scripts/git_revision_dates.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/git_revision_dates.py) hook rewires the *git-revision-date-localized* plugin to reference original source paths rather than the generated `_web/` files (which are ignored by Git).
- **Internationalization**: [`scripts/site_i18n.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/site_i18n.py) generates a client-side translation catalog enabling the language switcher functionality.
- **Markdown cleanup**: [`scripts/mkdocs_pandoc_strip.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/mkdocs_pandoc_strip.py) removes Pandoc-specific attributes and LaTeX syntax that Python-Markdown cannot parse.
- **Search optimization**: [`scripts/split_search_index.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/split_search_index.py) splits the large search index into per-edition JSON chunks for faster loading.

MkDocs reads the configuration, applies these pre-processing hooks, and writes the final static site to the `site/` directory.

### Stage 3: GitHub Pages Deployment

The **deployment stage** is fully automated via [`.github/workflows/deploy-pages.yml`](https://github.com/bojieli/ai-agent-book/blob/main/.github/workflows/deploy-pages.yml). The workflow triggers on pushes to `main` or manual dispatch:

1. **Environment setup**: Installs Python dependencies from [`requirements-docs.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements-docs.txt) and sets `NO_MKDOCS_2_WARNING=1` to suppress MkDocs 2.0 banners.
2. **Site generation**: Executes `bash scripts/build_site.sh` to create `_web/`, then runs `mkdocs build -d site` to render the static files.
3. **Artifact upload**: Uploads the `site/` directory as a GitHub Pages artifact.
4. **Deployment**: Publishes to GitHub Pages using `actions/deploy-pages@v5`, but only when the repository matches the canonical owner (`bojieli/ai-agent-book`).

This ensures the live site at `https://bojieli.github.io/ai-agent-book` always reflects the latest committed changes.

## Local Development Workflow

You can replicate the **MkDocs site build and deployment** process locally for testing:

```bash

# Install dependencies (requires Python 3.11+)

pip install -r requirements-docs.txt

# Assemble the documentation tree

bash scripts/build_site.sh

# Build the static site

mkdocs build -d site

# Or serve locally for development

mkdocs serve

```

The local server exposes the site at `http://127.0.0.1:8000/` with live reload enabled.

## Summary

- **Assembly**: [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh) transforms raw book sources into the `_web/` directory, handling chapter promotion, multilingual support, and asset normalization.
- **Configuration**: [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml) orchestrates the Material theme and loads custom hooks from `scripts/` for revision dates, i18n, and Markdown cleanup.
- **CI/CD**: [`.github/workflows/deploy-pages.yml`](https://github.com/bojieli/ai-agent-book/blob/main/.github/workflows/deploy-pages.yml) automates the full pipeline from source commit to GitHub Pages deployment using `actions/deploy-pages@v5`.
- **Separation**: The pipeline maintains clean separation between source content (root directory) and generated artifacts (`_web/` and `site/`).

## Frequently Asked Questions

### How does the build script handle multiple languages?

The [`build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_site.sh) script copies each language edition from directories named `book-<lang>` into the assembled `_web/` structure. It also processes `index.*.md` files for language-specific homepages. The [`scripts/site_i18n.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/site_i18n.py) hook then generates a client-side translation catalog that powers the language switcher in the Material theme navigation.

### Why are chapter files converted to index.md during assembly?

MkDocs expects directory-based URLs (e.g., `/book/chapter1/`) rather than file-based URLs (e.g., [`/book/chapter1.html`](https://github.com/bojieli/ai-agent-book/blob/main//book/chapter1.html)). The assembly script promotes each [`chapterN.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapterN.md) to [`chapterN/index.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapterN/index.md) and uses `sed` to rewrite relative image paths, ensuring assets resolve correctly under the site's URL scheme while maintaining clean permalinks.

### Can I deploy the site to a different hosting provider?

Yes. The `mkdocs build` command generates a standard static site in the `site/` directory containing only HTML, CSS, and JavaScript. You can deploy this folder to any static hosting service (Netlify, Vercel, AWS S3) by modifying the final step in [`.github/workflows/deploy-pages.yml`](https://github.com/bojieli/ai-agent-book/blob/main/.github/workflows/deploy-pages.yml) or by uploading the `site/` directory manually after local builds.

### What Python version is required for local builds?

The project requires **Python 3.11 or higher** as specified in the CI workflow and dependency constraints. The [`requirements-docs.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements-docs.txt) file pins compatible versions of MkDocs Material (9.x) and plugins to ensure reproducible builds across local environments and GitHub Actions runners.