跳转至

Local Development Guide

本文档说明如何在 Windows 本地从 0 到 1 搭建 MkDocs 开发环境, 并保证本地行为与 GitHub Pages 自动部署保持一致.

Environment Overview

本项目在 GitHub Actions 中使用的构建环境为:

  • OS: Ubuntu (GitHub Actions runner)
  • Python: 3.11
  • Package manager: pip
  • Documentation tool: MkDocs

在 Windows 本地, 我们 只对齐 Python 版本与依赖, 不强求操作系统一致.

Prerequisites

  • Windows 10 / 11
  • Miniconda (推荐用于隔离 Python 环境)
  • Git

Install Miniconda

请从官方页面下载并安装 Miniconda (Windows x64):

https://docs.conda.io/en/latest/miniconda.html

安装建议:

  • 勾选 “Add Miniconda to PATH”
  • 不要将其注册为系统默认 Python

Create Conda Environment

在项目根目录打开 PowerShell, 执行:

conda create -n mkdocs-py311 python=3.11 -y
conda activate mkdocs-py311

确认 Python 版本:

python --version
# Python 3.11.x

Install Project Dependencies

进入文档目录并安装依赖:

cd docs
pip install -r requirements.txt

说明:

  • 本项目在 CI 中通过 make install 安装依赖
  • 在 Windows 上不需要 make
  • 上述命令与 CI 行为等价

Local Preview

启动本地开发服务器:

mkdocs serve

然后在浏览器中访问: http://127.0.0.1:8000/

此模式适用于日常文档编写与实时预览.

Local Build (Optional)

如需验证构建结果:

mkdocs build --strict

生成的静态文件位于:

docs/site/

Deployment Model

本项目采用以下部署策略:

  • 本地:

    • 编写 Markdown
    • 使用 mkdocs serve 进行预览

  • 远端:

    • git push 到 main 分支
    • GitHub Actions 自动构建并部署到 GitHub Pages

本地 不建议 运行 mkdocs gh-deploy.

Notes

  • Windows 环境下默认没有 make, 属于正常情况
  • 请勿在本地直接推送 gh-pages 分支
  • 所有线上部署均由 GitHub Actions 负责

Summary

通过以上流程, 你可以在 Windows 本地获得一个: - 与 CI 行为一致 - 不污染系统 Python - 可长期维护的 MkDocs 开发环境

把它接入导航

在 docs/mkdocs.yml 中加入一行:

nav:
  - Home: index.md
  - Hello World: hello-world.md
  - Local Development: local-development.md
  - About: about-mkdocs.md

四、提交即可生效

git add docs/docs/local-development.md docs/mkdocs.yml
git commit -m "Add local development guide"
git push