How to Deploy the AI Agent Book Application

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, 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. 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 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, 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 and 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:

# 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:

# 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:

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 script assembles content into _web/ and normalizes links before building.
• .github/workflows/deploy-pages.yml automates deployment to GitHub Pages on every push to main.
• Local deployment requires installing dependencies from 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 GitHub Actions workflow. This workflow installs Python dependencies, executes 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 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 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.

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