# How to Deploy the AI Agent Book Application

> Learn to deploy the AI Agent Book application on GitHub Pages. Explore automated GitHub Actions workflows and manual builds for your static site.

- 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 application deploys as a static website generated by MkDocs Material and hosted on GitHub Pages, utilizing either an automated GitHub Actions workflow or manual local builds pushed to the `gh-pages` branch.**

The `bojieli/ai-agent-book` repository contains a documentation project that transforms Markdown sources into a polished static site. According to the source code, the deployment pipeline follows a three-stage architecture: site assembly, MkDocs rendering, and GitHub Pages publication. This guide explains both automated and manual deployment methods while referencing the actual build scripts and configuration files from the repository.

## Deployment Architecture Overview

The deployment pipeline consists of three coordinated components that convert raw Markdown into production-ready HTML.

### Site Assembly with build_site.sh

The process begins with [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh), a bash script that prepares the documentation structure for MkDocs consumption. This script copies the Markdown sources from the `book/` folder, along with language editions, experiment directories, and static assets, into a temporary `_web/` directory. Crucially, it normalizes relative links to ensure compatibility with MkDocs' directory-URL scheme.

### Static Site Generation via MkDocs

The assembled `_web/` folder serves as input to the MkDocs build process defined in [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml). Executing `mkdocs build -d site` renders the Markdown to HTML, applies the Material theme, generates navigation structures, and creates search indices and social-card metadata through custom hooks defined in the configuration.

### GitHub Pages Publication

The [`.github/workflows/deploy-pages.yml`](https://github.com/bojieli/ai-agent-book/blob/main/.github/workflows/deploy-pages.yml) GitHub Actions workflow orchestrates the final publication stage. Triggered on every push to the `main` branch, this workflow installs Python dependencies from [`requirements-docs.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements-docs.txt), executes the build script, compiles the site to the `site/` directory, and invokes `actions/deploy-pages` to publish the content to `https://bojieli.github.io/ai-agent-book/`.

## Deployment Methods

Because the output is purely static HTML, you can deploy the AI Agent Book using either automated CI/CD or manual processes.

### Automatic CI/CD Deployment (Recommended)

Committing any change to the `main` branch automatically triggers the deployment workflow. The GitHub Actions runner handles dependency installation, site assembly, building, and publication without requiring local intervention. This method guarantees that the live site always reflects the latest committed changes.

### Manual Local Deployment

For testing custom modifications or deploying to alternative hosting environments, you can build the site locally and manually push the generated HTML. This approach uses the same [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh) and [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml) configuration as the automated pipeline, ensuring identical output.

## Step-by-Step Local Build and Deployment

Follow these commands to build and preview the AI Agent Book application on your local machine:

```bash

# 1. Install the required Python packages

pip install -r requirements-docs.txt

# 2. Assemble the documentation files and normalize links

bash scripts/build_site.sh

# 3. Build the static site (output goes to ./site)

mkdocs build

# 4. Serve locally for preview at http://127.0.0.1:8000

mkdocs serve

```

To manually deploy the built site to GitHub Pages without using the automated workflow:

```bash

# After running the build steps above (site/ now contains the HTML)

# 1. Create a fresh orphan branch for GitHub Pages

git checkout --orphan gh-pages
git rm -rf .

# 2. Move the built site into the root of the branch

cp -r site/* .

# 3. Commit and push to trigger GitHub Pages publication

git add .
git commit -m "Deploy latest AI Agent Book site"
git push -u origin gh-pages --force

```

Alternatively, trigger the CI workflow manually through the GitHub UI by navigating to **Actions → deploy-pages → Run workflow**, or execute via the GitHub CLI:

```bash
gh workflow run deploy-pages.yml

```

## Summary

- The AI Agent Book uses **MkDocs Material** to generate static HTML from Markdown sources located in the `book/` directory.
- The **[`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh)** script assembles content into `_web/` and normalizes links before building.
- **[`.github/workflows/deploy-pages.yml`](https://github.com/bojieli/ai-agent-book/blob/main/.github/workflows/deploy-pages.yml)** automates deployment to GitHub Pages on every push to `main`.
- Local deployment requires installing dependencies from **[`requirements-docs.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements-docs.txt)**, running the build script, and either serving with `mkdocs serve` or pushing the `site/` directory to the `gh-pages` branch.
- The production site is hosted at `https://bojieli.github.io/ai-agent-book/`.

## Frequently Asked Questions

### What triggers the automatic deployment of the AI Agent Book?

Pushing any commit to the `main` branch triggers the [`.github/workflows/deploy-pages.yml`](https://github.com/bojieli/ai-agent-book/blob/main/.github/workflows/deploy-pages.yml) GitHub Actions workflow. This workflow installs Python dependencies, executes [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh), runs `mkdocs build`, and publishes the resulting `site/` directory to GitHub Pages.

### Can I deploy the AI Agent Book to hosting providers other than GitHub Pages?

Yes. Because the `mkdocs build` command generates a self-contained static website in the `site/` directory, you can deploy these files to any static hosting service, including Netlify, Vercel, or AWS S3. Simply upload the contents of the `site/` folder after running the local build process.

### What Python dependencies are required to build the site locally?

The repository includes a [`requirements-docs.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements-docs.txt) file that pins all necessary packages, including MkDocs Material and its extensions. Install these dependencies using `pip install -r requirements-docs.txt` before attempting to build or serve the documentation locally.

### How does the build process handle multilingual content?

The [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/build_site.sh) script copies language editions from the source directory alongside the main `book/` content into the temporary `_web/` assembly directory. It normalizes relative links across all language variants to ensure proper navigation under the MkDocs directory structure, allowing the Material theme's language switcher to function correctly as configured in [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml).