Skip to content

Documentation Site Publishing Guide

This repository's documentation site is powered by MkDocs Material and supports two free hosting options. The code and configuration are already prepared. Only the steps marked as actions for you need to be completed before going online.

Documentation Site Stack

Component Description
Documentation framework MkDocs Material, a popular open-source documentation theme
Multilingual plugin mkdocs-static-i18n, used to build Chinese and English static pages
Configuration file mkdocs.yml in the repository root
Documentation source Maintained Markdown files under docs/; pages no longer reference old example directories or external README files
Home page index.md
Build output site/ directory, ignored by .gitignore and not committed
Deployment option A GitHub Actions -> GitHub Pages, recommended and simplest
Deployment option B Cloudflare Pages, faster for mainland China and unlimited bandwidth

Local Preview

# Install dependencies.
pip install mkdocs mkdocs-material mkdocs-static-i18n pymdown-extensions

# Preview locally. Open http://127.0.0.1:8000 in the browser.
mkdocs serve

# Build locally. Output is written to site/.
mkdocs build --clean

Option A: GitHub Pages

How It Works

The required files are already configured:

  1. mkdocs.yml: documentation site configuration.
  2. .github/workflows/docs-pages.yml: GitHub Actions workflow for automatic build and deployment.
  3. When you push to the master branch and documentation-related files have changed, the workflow installs MkDocs, builds the site, and publishes it to GitHub Pages.

What You Need to Do Once

Prerequisite

You need admin permission for the charliedream1/ai_quant_trade repository.

Step 1: Confirm the Workflow Has Been Pushed

Open the Actions tab in the GitHub repository. You should see the workflow named Deploy MkDocs to GitHub Pages. If it is missing, the current commit has not been pushed yet. Run:

git push origin master

Step 2: Enable GitHub Pages from GitHub Actions

  1. Open https://github.com/charliedream1/ai_quant_trade/settings/pages
  2. In Build and deployment, set Source to GitHub Actions. Do not choose "Deploy from a branch".
  3. The page saves automatically.

Step 3: Trigger the First Deployment

  • Automatic: modify any documentation file and push to master.
  • Manual: open the Actions tab, choose Deploy MkDocs to GitHub Pages, click Run workflow, choose the master branch, and run it.

Step 4: Visit the Site

After deployment succeeds, usually in 2-3 minutes, open:

https://charliedream1.github.io/ai_quant_trade/

Ongoing Maintenance

After setup, every documentation push to master automatically rebuilds and publishes the site. No manual deployment is needed.

Common Issues

GitHub Actions fails during mkdocs build

Check whether the paths referenced by nav in mkdocs.yml exist. With the bilingual setup, every nav page must also have an English .en.md counterpart.

GitHub Pages shows 404
  1. Confirm Settings -> Pages uses GitHub Actions as the source.
  2. Confirm the latest run in the Actions tab is successful.
  3. The first GitHub Pages deployment may take 5-10 minutes to become available.
How do I change theme color or navigation?

Edit mkdocs.yml: - Theme color: theme.palette.primary - Navigation: nav - English navigation labels: plugins.i18n.languages[].nav_translations

Option B: Cloudflare Pages

When to Use It

  • Most readers are in mainland China, where Cloudflare Pages may be faster than GitHub Pages.
  • You are concerned about GitHub Pages bandwidth limits.
  • You want extra security features such as DDoS protection.

What You Need to Do Once

Step 1: Register a Cloudflare Account

Open https://dash.cloudflare.com/sign-up and register. The free plan is enough and does not require a credit card.

Step 2: Create a Pages Project

  1. Log in and open https://dash.cloudflare.com/
  2. Choose Workers & Pages from the left sidebar.
  3. Click Create application -> Pages -> Connect to Git.
  4. Authorize Cloudflare to access your GitHub account, then select the ai_quant_trade repository.

  5. Fill in the project configuration:

    Setting Value
    Project name ai-quant-trade-docs
    Production branch master
    Framework preset None
    Build command bash .cloudflare/scripts/build.sh
    Build output directory site
    Environment variables PYTHON_VERSION = 3.11

  6. Click Save and Deploy.

Step 3: Wait for the First Build

Cloudflare pulls the code, runs build.sh, builds the site, and deploys it. This usually takes 3-5 minutes. The build log is visible in the Pages project.

Step 4: Visit the Site

After deployment succeeds, Cloudflare provides a domain such as:

https://ai-quant-trade-docs.pages.dev/

Ongoing Maintenance

Every push to master triggers Cloudflare to pull the latest code, run the build script, and deploy the generated site/ directory.

Optional: Bind a Custom Domain

  1. Open the Pages project.
  2. Choose Custom domains -> Set up a custom domain.
  3. Enter a domain such as docs.yourdomain.com.
  4. Add the CNAME record requested by Cloudflare.
  5. Cloudflare automatically provisions HTTPS.

Common Issues

Build fails because the Python version is wrong

Add PYTHON_VERSION=3.11 under Cloudflare Pages -> Settings -> Environment variables, then redeploy.

pip install times out

Retry once. If it still fails, set PIP_INDEX_URL to https://pypi.tuna.tsinghua.edu.cn/simple in the Cloudflare Pages environment variables.

Comparison

Dimension GitHub Pages Cloudflare Pages
Manual setup One setting in GitHub Pages Account, authorization, and project configuration
Setup time About 2 minutes About 5 minutes
Bandwidth 100 GB/month Unlimited
Mainland China access Average Better
Commercial use Ambiguous Explicitly allowed
HTTPS Automatic Automatic
Custom domain Supported Supported
Extra features None DDoS protection and Workers

Recommendation

Use only one deployment path unless you intentionally want two domains. GitHub Pages is the default recommendation because it has the least setup work. Cloudflare Pages is better when most readers are in mainland China.

Already Prepared

File Purpose
mkdocs.yml Main documentation site configuration
index.md Chinese home page
index.en.md English home page
.github/workflows/docs-pages.yml GitHub Pages deployment workflow
.cloudflare/scripts/build.sh Cloudflare Pages build script
.cloudflare/wrangler.toml Optional Cloudflare CLI deployment config
.gitignore Excludes generated site/ output

Troubleshooting Checklist

If deployment fails, check these items in order:

  1. Can the site build locally? 

    pip install mkdocs mkdocs-material mkdocs-static-i18n pymdown-extensions
mkdocs build --strict --clean
    If local build fails, fix the reported file path, link, or i18n issue first.

  2. GitHub Actions logs Open https://github.com/charliedream1/ai_quant_trade/actions and inspect the failed run.

  3. Cloudflare build logs Cloudflare Dashboard -> Pages -> your project -> Deployments -> failed deployment.

  4. Pages settings Open https://github.com/charliedream1/ai_quant_trade/settings/pages and confirm the source is GitHub Actions.

If you still run into issues, open an issue at https://github.com/charliedream1/ai_quant_trade/issues.