Static Webpage Deployment Tutorial

Introduction

This page tells how to create static webpages through MKDocs & Github and host them on cloudflare.

MKDocs Usage Guide

场景推荐用 Cloudflare Pages + GitHub Git 集成：GitHub 仓库里只放 MkDocs 源文件，Cloudflare 每次检测到 main 分支更新后自动执行 mkdocs build，然后把生成的 site/ 目录部署出去。Cloudflare Pages 官方 MkDocs 配置就是：Build command = mkdocs build，Build directory = site。(Cloudflare Docs) 另外，Cloudflare Pages 支持连接 GitHub 的 public/private repo，所以仓库不用公开。(Cloudflare Docs)

下面按从零开始写。

一、最终目录结构

最后你的 GitHub 仓库大概长这样：

my-mkdocs-site/
├── docs/
│   └── index.md
├── mkdocs.yml
├── requirements.txt
├── .python-version
└── .gitignore

核心逻辑是：

GitHub repo 源文件
        ↓ push
Cloudflare Pages 自动拉取
        ↓ mkdocs build
生成 site/
        ↓
部署到 xxx.pages.dev / 自定义域名

二、本地创建 MkDocs 项目

1. 新建项目目录

Windows PowerShell / macOS / Linux 都类似：

mkdir my-mkdocs-site
cd my-mkdocs-site

2. 创建 Python 虚拟环境

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS / Linux：

python3 -m venv .venv
source .venv/bin/activate

升级 pip：

python -m pip install --upgrade pip

3. 安装 MkDocs 和 Material 主题

基础版只装 MkDocs：

pip install mkdocs

更推荐直接用 Material 主题，观感好很多：

pip install mkdocs mkdocs-material

Cloudflare 官方 MkDocs 指南也是先本地安装 MkDocs，再通过 mkdocs new 创建项目，并把依赖写进 requirements.txt。(Cloudflare Docs)

三、初始化 MkDocs 文件

在当前目录执行：

mkdocs new .

这会生成：

docs/index.md
mkdocs.yml

你可以先把 docs/index.md 改成：

cat > docs/index.md << 'EOF'
# 我的文档站

这是通过 MkDocs + GitHub + Cloudflare Pages 托管的网页。
EOF

Windows PowerShell 不支持上面这种 cat << EOF 写法的话，可以直接用 VS Code 打开改：

code .

四、配置 `mkdocs.yml`

打开 mkdocs.yml，改成类似这样：

site_name: My Docs
site_description: My MkDocs site deployed on Cloudflare Pages
site_url: https://your-project.pages.dev/

theme:
  name: material
  language: zh

nav:
  - 首页: index.md

如果你以后要绑定自己的域名，比如 docs.example.com，再把：

site_url: https://docs.example.com/

site_url 不是部署成功的必要条件，但建议填，方便 sitemap、canonical URL 等生成正确。

五、固定 Python 版本和依赖

Cloudflare Pages 当前 build image 支持通过 PYTHON_VERSION 环境变量、.python-version 或 runtime.txt 指定 Python 版本；v3 build image 默认 Python 是 3.13.3，但为了兼容 MkDocs 插件，我建议用 Python 3.11。(Cloudflare Docs)

在仓库根目录创建 .python-version：

echo "3.11.9" > .python-version

然后创建 requirements.txt。简单写法：

cat > requirements.txt << 'EOF'
mkdocs
mkdocs-material
EOF

更稳的锁版本写法是：

pip freeze > requirements.txt

但注意，如果你的虚拟环境里装了很多乱七八糟的包，pip freeze 会把它们全写进去。所以我更建议初期手写：

mkdocs
mkdocs-material

如果你用了插件，比如搜索、多语言、git-revision-date 等，就继续加：

mkdocs
mkdocs-material
mkdocs-git-revision-date-localized-plugin
mkdocs-minify-plugin

六、添加 `.gitignore`

Cloudflare 会自己构建 site/，所以本地生成的 site/ 不需要提交。

cat > .gitignore << 'EOF'
.venv/
site/
.cache/
__pycache__/
*.pyc
EOF

七、本地测试

先启动本地预览：

mkdocs serve

默认会在：

http://127.0.0.1:8000/

然后测试能否正常 build：

mkdocs build --strict

如果成功，会生成：

site/

这个 site/ 就是 Cloudflare Pages 之后要部署的目录。Cloudflare Pages 的构建逻辑就是通过 build command 生成输出目录，然后上传输出目录内容。(Cloudflare Docs)

八、推送到 GitHub 仓库

方案 A：你已经在 GitHub 创建了仓库

假设仓库地址是：

https://github.com/YOUR_NAME/YOUR_REPO.git

执行：

git init
git add .
git commit -m "Initial MkDocs site"
git branch -M main
git remote add origin https://github.com/YOUR_NAME/YOUR_REPO.git
git push -u origin main

Cloudflare 官方 MkDocs 指南里的 GitHub 推送流程也是这一套：git init、添加远程仓库、git add、git commit、切到 main、git push。(Cloudflare Docs)

方案 B：用 GitHub CLI 创建私有仓库

如果你装了 GitHub CLI：

gh auth login
gh repo create my-mkdocs-site --private --source=. --remote=origin --push

如果你希望公开仓库，把 --private 换成：

--public

九、在 Cloudflare Pages 连接 GitHub

进入 Cloudflare Dashboard：

Workers & Pages
→ Create application
→ Pages
→ Connect to Git / Import an existing Git repository

Cloudflare Pages 的 Git integration 会在你 push 到已连接的 GitHub/GitLab 仓库后自动构建和部署。(Cloudflare Docs)

然后选择你的 GitHub 仓库。如果是私有仓库，授权的时候选择：

Only select repositories

然后勾选你的 MkDocs 仓库即可。Cloudflare 官方也建议尽量只给 Cloudflare GitHub App 授权需要构建的仓库，别一口气授权全部仓库，安全一点。(Cloudflare Docs)

十、Cloudflare Pages 构建配置

在 Cloudflare Pages 的 Set up builds and deployments 页面填：

Project name: my-mkdocs-site
Production branch: main
Framework preset: None / MkDocs 如果有
Build command: mkdocs build
Build output directory: site
Root directory: /

官方 MkDocs 页面明确写的就是：

Production branch: main
Build command: mkdocs build
Build directory: site

(Cloudflare Docs)

如果你的 MkDocs 项目不在仓库根目录，而是在子目录，比如：

repo/
└── docs-site/
    ├── mkdocs.yml
    ├── requirements.txt
    └── docs/

那 Cloudflare 里要设置：

Root directory: docs-site
Build command: mkdocs build
Build output directory: site

Cloudflare Pages 默认从仓库根目录开始构建；monorepo 或项目在子目录时，需要在 Root directory 里指定路径。(Cloudflare Docs)

十一、环境变量设置

如果你已经提交了 .python-version，一般不用再配环境变量。

但如果你想在 Cloudflare UI 里设置，就填：

Variable name: PYTHON_VERSION
Value: 3.11.9

Cloudflare Pages 支持用环境变量或项目根目录文件来覆盖语言版本。(Cloudflare Docs)

所以二选一即可：

方式一：仓库里放 .python-version
方式二：Cloudflare 里设置 PYTHON_VERSION

我更推荐 .python-version，因为配置跟着仓库走，之后换设备、换 Cloudflare 项目都不容易忘。

十二、点击部署

点：

Save and Deploy

Cloudflare 会自动执行类似流程：

pip install -r requirements.txt
mkdocs build

然后部署 site/。

部署成功后，你会拿到一个地址：

https://my-mkdocs-site.pages.dev/

Cloudflare 官方说明，首次部署后会给项目一个唯一的 URL；之后每次 push 代码，Pages 会自动 rebuild/deploy。(Cloudflare Docs)

十三、以后如何更新网页

你只需要改 Markdown 文件，然后 push。

比如新增一页：

mkdir -p docs/research
cat > docs/research/index.md << 'EOF'
# Research

这里放研究笔记。
EOF

然后修改 mkdocs.yml：

site_name: My Docs
site_url: https://your-project.pages.dev/

theme:
  name: material
  language: zh

nav:
  - 首页: index.md
  - 研究:
      - Research: research/index.md

本地测试：

mkdocs serve

确认没问题后：

git add .
git commit -m "Add research page"
git push

Cloudflare 会自动重新部署。Cloudflare GitHub integration 会在你 push 分支更新时自动部署。(Cloudflare Docs)

十四、绑定自定义域名

比如你想用：

docs.example.com

进入：

Cloudflare Dashboard
→ Workers & Pages
→ 你的 Pages 项目
→ Custom domains
→ Set up a domain
→ 输入 docs.example.com

Cloudflare 官方自定义域名流程就是在 Pages 项目的 Custom domains 里添加域名。(Cloudflare Docs)

如果你的域名 DNS 已经托管在 Cloudflare，Cloudflare 通常会自动创建 DNS 记录。如果 DNS 不在 Cloudflare，你需要在原 DNS 服务商那里加 CNAME：

Type: CNAME
Name: docs
Target: your-project.pages.dev

Cloudflare 文档也说明，子域名可以通过 CNAME 指向 <YOUR_SITE>.pages.dev；但必须先在 Pages Dashboard 里添加 custom domain，只手动加 CNAME 不够，否则可能解析失败。(Cloudflare Docs)

然后把 mkdocs.yml 里的 site_url 改成：

site_url: https://docs.example.com/

提交：

git add mkdocs.yml
git commit -m "Set custom domain site_url"
git push

十五、几个常见坑

1. 不要用 `mkdocs gh-deploy`

mkdocs gh-deploy 是给 GitHub Pages 用的，会生成/推送 gh-pages 分支。你现在用 Cloudflare Pages，不需要它。你只要 push 源码到 main，Cloudflare 自己 build。

2. 报错：`mkdocs: command not found`

通常是 requirements.txt 没写 MkDocs。

检查：

cat requirements.txt

至少应该有：

mkdocs

如果用了 Material：

mkdocs-material

3. 报错：`Output directory "site" not found`

说明 mkdocs build 没成功，或者 Cloudflare 的输出目录写错了。

Cloudflare 里必须是：

Build command: mkdocs build
Build output directory: site

不要写成：

Build output directory: docs

docs/ 是源文件目录，site/ 才是构建后的静态网页目录。

4. 私有仓库找不到

去 GitHub：

Settings
→ Applications
→ Installed GitHub Apps
→ Cloudflare Workers and Pages
→ Configure

把 Repository access 改成：

Only select repositories

然后勾选你的仓库。Cloudflare 文档也说，如果 Cloudflare Pages 无法访问 GitHub repo，可以尝试重新安装/配置 GitHub App。(Cloudflare Docs)

5. 仓库 private 不等于网页 private

GitHub 仓库可以是 private，但 Cloudflare Pages 部署出来的网站默认是公开可访问的。Cloudflare Pages 的 preview deployment 默认也是公开的；Cloudflare 提供 Access policy 来限制 preview deployments，但这默认只保护预览部署，不保护正式的 *.pages.dev 或自定义域名。(Cloudflare Docs)

所以如果你是“内部文档站”，还要额外上 Cloudflare Access / Zero Trust，而不是只把 GitHub 仓库设成 private。

十六、一套最小可用命令总结

你可以直接按这个跑：

mkdir my-mkdocs-site
cd my-mkdocs-site

python -m venv .venv
source .venv/bin/activate   # Windows PowerShell 用：.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
pip install mkdocs mkdocs-material

mkdocs new .

cat > mkdocs.yml << 'EOF'
site_name: My Docs
site_url: https://my-mkdocs-site.pages.dev/

theme:
  name: material
  language: zh

nav:
  - 首页: index.md
EOF

cat > docs/index.md << 'EOF'
# 我的文档站

这是通过 MkDocs + GitHub + Cloudflare Pages 托管的网页。
EOF

cat > requirements.txt << 'EOF'
mkdocs
mkdocs-material
EOF

echo "3.11.9" > .python-version

cat > .gitignore << 'EOF'
.venv/
site/
.cache/
__pycache__/
*.pyc
EOF

mkdocs build --strict

git init
git add .
git commit -m "Initial MkDocs site"
git branch -M main
git remote add origin https://github.com/YOUR_NAME/YOUR_REPO.git
git push -u origin main

然后 Cloudflare Pages 里填：

Production branch: main
Build command: mkdocs build
Build output directory: site
Root directory: /

这样就能跑起来。