Documentation Site Generation

Relevant source files

This document describes the MkDocs-based static site generation system that transforms the LeetCode solutions repository into a bilingual documentation website deployed to GitHub Pages. The system preprocesses problem solutions, generates navigation structures, builds separate Chinese and English sites, and deploys them automatically via GitHub Actions.

For information about the data acquisition and content structure feeding into this system, see Data Acquisition System and Content Generation Pipeline. For the CI/CD workflows orchestrating the build process, see CI/CD and Deployment.

System Architecture

The documentation site generation system operates as a multi-stage pipeline that merges content from two branches, preprocesses it, builds bilingual static sites, and deploys them to GitHub Pages.

Sources: .github/workflows/deploy.yml1-154

The system consists of:

Content Sources: Problem solutions from main branch, configuration from docs branch
Preprocessing: Python script transforms raw content into MkDocs-compatible structure
Build Stage: MkDocs generates static HTML for both languages
Deployment: Compressed site uploaded to GitHub Pages

Dual-Branch Content Strategy

The documentation generation merges content from two branches to separate concerns between content and configuration:

Sources: .github/workflows/deploy.yml25-42

Branch Merge Process

The deploy.yml workflow performs the following merge operations:

Step	Command	Purpose
Checkout main	`actions/checkout@v4`	Fetch problem solutions and metadata
Checkout docs	`ref: docs, path: mkdocs/`	Fetch MkDocs configuration separately
Merge content	`rsync -a --remove-source-files --exclude='.git' mkdocs/ ./`	Copy docs branch content to workspace root
Move contest files	`mv solution/CONTEST_README.md docs/contest.md`	Relocate contest documentation

Sources: .github/workflows/deploy.yml38-42

Build Pipeline Execution

The complete build process executes in a Ubuntu environment with Python and MkDocs Material theme:

Sources: .github/workflows/deploy.yml1-124

Dependency Installation

The build requires the following dependencies:

black==24.3.0 Requests==2.32.4 mkdocs-material[imaging] pngquant (system package)

Sources: requirements.txt1-2 .github/workflows/deploy.yml70-75

The mkdocs-material[imaging] package includes support for social cards and image optimization. The pngquant system package provides additional image compression capabilities.

Preprocessing System

The main.py script executes before MkDocs builds to transform repository content into documentation-ready format:

Sources: .github/workflows/deploy.yml82

Problem Documentation Structure

Each problem's documentation follows a standardized format that the preprocessing system relies on:

Component	Location	Description
Frontmatter	Lines 1-8	YAML metadata with difficulty, tags, edit_url
Problem Title	Line 12	Chinese/English problem title with number
Description	Lines 17+	Problem statement in HTML/Markdown
Solutions	Multiple sections	Solution explanations with complexity analysis
Code Tabs	Within solutions	Multi-language code snippets

Example Structure:

Sources: solution/0100-0199/0125.Valid Palindrome/README.md1-8 solution/0100-0199/0125.Valid Palindrome/README_EN.md1-8

MkDocs Configuration

The system maintains two separate MkDocs configuration files for bilingual support:

Sources: .github/workflows/deploy.yml83-84

Key Configuration Parameters

Both configuration files specify:

Parameter	Purpose	Value
`docs_dir`	Source directory for Markdown	`docs/` or `docs-en/`
`site_dir`	Output directory for HTML	`site/cn/` or `site/en/`
`site_name`	Website title	"LeetCode 题解" / "LeetCode Solutions"
`site_url`	Base URL	`https://leetcode.doocs.org`
`theme`	MkDocs theme	`material` with custom config

Content Directory Structure

The documentation directories are organized to mirror the repository structure:

docs/ # Chinese documentation ├── contest.md # Contest rankings and history ├── solution/ │ ├── 0000-0099/ │ ├── 0100-0199/ │ └── ... ├── lcof/ # 剑指 Offer problems ├── lcci/ # Cracking the Coding Interview ├── lcp/ # LeetCode Cup problems └── basic/ # Basic algorithms tutorials docs-en/ # English documentation (same structure)

Sources: .github/workflows/deploy.yml41-42

Deployment to GitHub Pages

The deployment stage uploads the built site to GitHub Pages using the actions/deploy-pages action:

Sources: .github/workflows/deploy.yml114-153

Deployment Job Configuration

The deployment job runs with specific permissions and environment settings:

Sources: .github/workflows/deploy.yml126-134

Setting	Value	Purpose
`needs`	`build`	Wait for build job completion
`pages: write`	Permission	Write access to GitHub Pages
`id-token: write`	Permission	OIDC token for deployment
`environment`	`github_pages`	Named environment for tracking

CNAME File

The workflow generates a CNAME file for custom domain configuration:

Sources: .github/workflows/deploy.yml86-87

This ensures the deployed site is accessible at the custom domain leetcode.doocs.org rather than the default doocs.github.io/leetcode URL.

Caching Strategy

The build process implements multi-level caching to reduce build times:

Sources: .github/workflows/deploy.yml54-68 .github/workflows/deploy.yml89-112

Cache Types

Pip Dependencies Cache
- Path: ~/.cache/pip
- Key: Based on requirements.txt hash
- Speeds up Python package installation
MkDocs Material Cache
- Path: .cache
- Key: Based on cache_id environment variable
- Caches theme assets and plugin data
Git Committers Cache
- Path: .git-committers-cache.json
- Storage: docs branch
- Tracks contributor information for git-committers plugin
- Conditionally committed back to repository

Sources: .github/workflows/deploy.yml95-112

The committer cache commit process includes safety checks:

Integration with Dynamic Assets

The documentation site incorporates dynamically generated assets produced by separate workflows:

Sources: .github/workflows/starcharts.yml1-20 images/starcharts.svg1-2 images/contributors.svg1-2

Starcharts Generation

The starcharts workflow runs on a schedule and generates a visualization of repository star growth:

Parameter	Value
Schedule	`0 0/12 * * *` (every 12 hours)
Action	`MaoLongLong/actions-starcharts@main`
Output	`images/starcharts.svg`
Commit message	"chore: auto update starcharts"
Token	`DOOCS_BOT_ACTION_TOKEN`

Sources: .github/workflows/starcharts.yml4-19

These SVG assets are then referenced in the documentation markdown files and included in the final static site build.

Workflow Triggers and Concurrency

The deployment workflow is triggered by specific file changes and implements concurrency control:

Trigger Conditions

Sources: .github/workflows/deploy.yml3-15

The workflow triggers when:

Manual workflow dispatch is requested
Changes are pushed to main branch affecting problem solution directories

Concurrency Control

Sources: .github/workflows/deploy.yml17-19

This ensures:

Only one deployment runs per branch at a time
New pushes cancel in-progress builds
Prevents conflicting deployments

Summary

The documentation site generation system transforms the repository's problem solutions into a production-ready bilingual website through a sophisticated pipeline:

Content merging from main (solutions) and docs (configuration) branches
Preprocessing via main.py to transform content structure
Dual builds using separate MkDocs configurations for Chinese and English
Artifact compression and upload to GitHub's artifact storage
Automated deployment to GitHub Pages with custom domain support

The system leverages GitHub Actions for automation, MkDocs Material for theming, and implements intelligent caching to optimize build performance. Dynamic assets like star charts integrate seamlessly through scheduled workflows, and the entire pipeline is triggered automatically when problem solutions are updated.

Sources: .github/workflows/deploy.yml1-154 requirements.txt1-2