MkDocs - 把文档变成网站

本地

操作系统：macOS

1 在 GitHub 建立仓库（默认建立 README.md），并 git clone 设置好.gitignore

# macOS
.DS_Store

# Python
venv/

# MkDocs
site/

2 在Python虚拟环境下安装 mkdocs 和 mkdocs material 主题

python3 -m venv venv
source venv/bin/activate
pip3 install mkdocs
pip3 install mkdocs-material 

3 mkdocs 初始化

mkdocs new .

在 mkdocs.yml 添加 theme: material

4 添加自己的 Markdown 文件到 docs 文件夹下

5 预览生成的网站效果 mkdocs serve - 访问 http://127.0.0.1:8000/ 查看效果

6 如果效果满意，提交一下

git add .
git commit -m "<your commit message>"
git push origin main # 第二次开始用 git push 即可

发布

网站可以添加到仓库的 Describtion 中，方便以后查看。

方式一：发布到 Netlify

1 在 Netlify 建立新站点，选择 GitHub 仓库，并关联。
2 在 Netlify 的 Site settings 中，设置 Build command 为 python3 -m pip install --upgrade pip && python3 -m pip install mkdocs>=1.5.0 mkdocs-material>=9.0.0 && python3 -m mkdocs build，Publish directory 为 site。
3 点击 Deploy site 按钮，Netlify 会自动发布网站。
4 访问 https://<your site name>.netlify.app 查看效果。

自定义域名：
1 域名商：
在 FastComet 的 cPanel 的 Zone Editor 中，添加一条 CNAME 记录，如notes.zoejane.com，指向 https://<your site name>.netlify.app。
2 Netlify：
在 Netlify 的 Site settings 中，设置 Custom domain 为 notes.zoejane.com。
稍等几分钟，等待 DNS 解析和 HTTPS 证书生效。
如果证书申请时间较长，可以在自定义域名的 Options 下拉菜单选择 Remove domain 后重新添加。

方式二：发布到 GitHub Pages

手动方式：本地手工处理 mkdocs gh-deploy
如果是第一次使用 gh-deploy，GitHub 会自动创建 gh-pages 分支，并且会自动设置 GitHub Pages。

自动方式：GitHub Actions 自动处理
建立 .github/workflows/ci.yml文件

name: ci 
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force 

• 访问网站
  https://<yourname>.github.io/<repo name>
  如果网站没有生成成功，可在GitHub 仓库设置中的 Pages 部分，确认是否选择了 gh-pages 分支。

Changelog

• 20250214 zoejane init