# How to Generate Documentation for the AI Agent Book: Complete MkDocs Build Guide > Learn to generate documentation for the AI agent book using MkDocs Material. Follow our complete guide for building a static site with preprocessing and multilingual support for easy GitHub Pages deployment. - Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book) - Tags: how-to-guide - Published: 2026-07-29 --- **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`](https://github.com/bojieli/ai-agent-book/blob/main/requirements-docs.txt). This file pins MkDocs, the Material theme, and extensions like `pymdown-extensions`. ```bash # 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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml)) The [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/lang-switcher.js), [`nav-collapse.js`](https://github.com/bojieli/ai-agent-book/blob/main/nav-collapse.js), and [`mermaid-init.js`](https://github.com/bojieli/ai-agent-book/blob/main/mermaid-init.js)) ### Preprocessing Pipeline Two custom hooks run before MkDocs processes the Markdown: **[`scripts/mkdocs_pandoc_strip.py`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs_pandoc_strip.py) and [`seo_meta.py`](https://github.com/bojieli/ai-agent-book/blob/main/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. ```bash # 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`](https://github.com/bojieli/ai-agent-book/blob/main/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. ```bash 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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/extras/lang-switcher.js) and styled by [`extras/lang-switcher.css`](https://github.com/bojieli/ai-agent-book/blob/main/extras/lang-switcher.css). The [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/requirements-docs.txt) to obtain MkDocs Material and required extensions. - **Configure builds** via [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml), which orchestrates the documentation structure and references custom hooks. - **Preprocess content** using [`scripts/mkdocs_pandoc_strip.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/mkdocs_pandoc_strip.py) to remove incompatible Pandoc syntax and [`scripts/seo_meta.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/seo_meta.py) to inject social media meta tags. - **Generate output** by running [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh) script copies raw manuscripts into `_web/` to create a clean build workspace where [`scripts/mkdocs_pandoc_strip.py`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml) configures a language switcher that maps different source directories to language codes, while [`extras/lang-switcher.js`](https://github.com/bojieli/ai-agent-book/blob/main/extras/lang-switcher.js) and [`extras/lang-switcher.css`](https://github.com/bojieli/ai-agent-book/blob/main/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.