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

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, renders it with MkDocs Material configured in mkdocs.yml, and deploys automatically to GitHub Pages via .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, which performs several critical transformations:

• Copies core content: Root index.md, language-specific homepages (index.*.md), and 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) into directory indices (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 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. The rendering stage applies the Material theme and executes several custom hooks:

• Theme configuration: The 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 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 generates a client-side translation catalog enabling the language switcher functionality.
• Markdown cleanup: scripts/mkdocs_pandoc_strip.py removes Pandoc-specific attributes and LaTeX syntax that Python-Markdown cannot parse.
• Search optimization: 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. The workflow triggers on pushes to main or manual dispatch:

1. Environment setup: Installs Python dependencies from 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:

# 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 transforms raw book sources into the _web/ directory, handling chapter promotion, multilingual support, and asset normalization.
• Configuration: 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 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 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 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). The assembly script promotes each chapterN.md to 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 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 file pins compatible versions of MkDocs Material (9.x) and plugins to ensure reproducible builds across local environments and GitHub Actions runners.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}