How to Generate Documentation for the AI Agent Book: Complete MkDocs Build Guide

The AI Agent Book documentation is built with MkDocs Material using a custom pipeline that preprocesses Markdown files, handles multilingual content, and outputs a static site to the site/ directory for GitHub Pages deployment.

The bojieli/ai-agent-book repository generates its documentation site from raw Markdown manuscripts using MkDocs Material. To successfully generate documentation for the AI Agent Book locally or in CI/CD, you must install Python dependencies, execute preprocessing hooks, and run the provided build scripts that handle Pandoc syntax stripping and SEO meta tag injection.

Prerequisites and Environment Setup

Before building the documentation, prepare a Python virtual environment with the required packages listed in requirements-docs.txt. This file pins MkDocs, the Material theme, and extensions like pymdown-extensions.

# Clone the repository

git clone https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book

# Create and activate virtual environment

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install documentation dependencies

pip install -r requirements-docs.txt

The requirements-docs.txt installs MkDocs, mkdocs-material, and supporting libraries required to process the book's Markdown sources and custom extensions.

Build Architecture Overview

The documentation generation relies on three core components: the MkDocs configuration file, Python preprocessing hooks, and a shell script orchestrator. Together, these handle the book's Pandoc-specific syntax, multilingual structure, and SEO optimization.

Core Configuration (mkdocs.yml)

The mkdocs.yml file at the repository root defines the site name, Material theme customization, plugin stack, and navigation structure. It references the preprocessing hooks in its hooks section and configures the language switcher that maps the book's nine language editions.

Key configuration elements include:

• Theme settings for the custom book styling
• Plugin definitions for search and navigation
• Extra JavaScript and CSS files located in extras/ (including lang-switcher.js, nav-collapse.js, and mermaid-init.js)

Preprocessing Pipeline

Two custom hooks run before MkDocs processes the Markdown:

scripts/mkdocs_pandoc_strip.py removes Pandoc and LaTeX-specific attributes (such as {.unnumbered} or {#sec:foo}) that the standard Markdown parser cannot interpret. This ensures compatibility between the manuscript source and MkDocs.

scripts/seo_meta.py dynamically injects Open Graph and Twitter Card meta tags into each page's HTML header, enabling rich link previews when the documentation is shared on social platforms.

Building the Static Site

Execute scripts/build_site.sh to generate the production-ready documentation. This script performs three critical operations:

1. Source Assembly: Copies raw Markdown files from book/, book-* directories, and chapter*/README.md paths into a temporary _web directory along with associated images.
2. Hook Execution: Runs the MkDocs build process (mkdocs build), which triggers mkdocs_pandoc_strip.py and seo_meta.py to process files in _web.
3. Output Generation: Writes the final static HTML to the site/ folder, which GitHub Pages serves automatically via the repository's configured Actions workflow.

# Build the documentation site

bash scripts/build_site.sh

# Output is available in the site/ directory

ls site/

The site/ directory contains fully rendered HTML, CSS, JavaScript assets, and the extras/book-theme.css customizations that style the multilingual interface.

Local Development Server

For iterative development with instant feedback, use MkDocs' built-in development server instead of the full build script.

mkdocs serve

This command starts a local server at http://127.0.0.1:8000 with hot-reload enabled. Changes to Markdown sources, configuration, or files in extras/ (such as extras/lang-switcher.css) trigger immediate browser updates. The local preview uses identical theme settings and plugins as the production build, ensuring consistency before deployment.

Multilingual and SEO Features

The build system supports nine language editions through a custom language switcher implemented in extras/lang-switcher.js and styled by extras/lang-switcher.css. The mkdocs.yml configuration maps these languages to their respective source directories, generating a tabbed navigation interface.

The SEO meta tags generated by scripts/seo_meta.py ensure each page includes appropriate title, description, and image metadata for search engine indexing and social sharing, without requiring manual HTML edits in the source Markdown.

Summary

• Install dependencies from requirements-docs.txt to obtain MkDocs Material and required extensions.
• Configure builds via mkdocs.yml, which orchestrates the documentation structure and references custom hooks.
• Preprocess content using scripts/mkdocs_pandoc_strip.py to remove incompatible Pandoc syntax and scripts/seo_meta.py to inject social media meta tags.
• Generate output by running scripts/build_site.sh, which assembles sources into _web/ and outputs static HTML to site/.
• Preview locally with mkdocs serve for rapid development iteration with hot-reload.
• Deploy automatically to GitHub Pages from the site/ directory using the repository's existing Actions workflow.

Frequently Asked Questions

What dependencies are required to build the AI Agent Book documentation?

You need Python 3 and the packages listed in requirements-docs.txt, which include MkDocs, mkdocs-material, and pymdown-extensions. Install them in a virtual environment to avoid conflicts with system packages.

Why does the build process use a temporary _web directory?

The scripts/build_site.sh script copies raw manuscripts into _web/ to create a clean build workspace where scripts/mkdocs_pandoc_strip.py can safely modify files without altering the original sources in book/ or book-*/ directories.

How does the documentation support multiple languages?

The mkdocs.yml configures a language switcher that maps different source directories to language codes, while extras/lang-switcher.js and extras/lang-switcher.css render the tabbed UI allowing readers to switch between the nine available language editions seamlessly.

Can I deploy the documentation to my own domain instead of GitHub Pages?

Yes. After running bash scripts/build_site.sh, take the contents of the generated site/ folder and upload them to any static hosting provider (Netlify, Vercel, AWS S3). The output is standard static HTML with no server-side dependencies required.

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