Skip to content

发布您的网站

将项目文档托管在 git 仓库中的一个好处是能够在推送新更改时自动部署。MkDocs 使这一过程变得极其简单。

GitHub Pages

如果您已经在 GitHub 上托管了代码，GitHub Pages 无疑是发布项目文档最方便的方式。它是免费的，设置起来也相当简单。

使用 GitHub Actions

通过使用 GitHub Actions，您可以自动化项目文档的部署。在您的仓库根目录中，创建一个新的 GitHub Actions 工作流，例如 .github/workflows/ci.yml，并复制粘贴以下内容：

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

  1. 您可以根据自己的喜好更改名称。

  2. 在某个时刻，GitHub 将 master 重命名为 main。如果您的默认分支名为 master，可以安全地删除 main，反之亦然。

  3. 存储 cache_id 环境变量，以便在创建缓存 key 时使用。名称区分大小写，请确保与 ${{ env.cache_id }} 对齐。

    • --utc 选项确保每个工作流运行器使用相同的时区。
    • %V 格式确保每周更新一次缓存。
    • 您可以将格式更改为 %F 以实现每日缓存更新。

    您可以阅读 手册页面 以了解有关 date 命令的格式选项的更多信息。

  4. 一些 Material for MkDocs 插件使用 缓存 来加速重复构建，并将结果存储在 ~/.cache 目录中。

  5. 这是安装其他 MkDocs 插件 或 Markdown 扩展的地方，使用 pip 在构建过程中使用：

    pip install \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \
  ...

现在，当新的提交推送到 master 或 main 分支时，静态网站将自动构建和部署。推送您的更改以查看工作流的实际运行。

如果 GitHub 页面在几分钟后仍未显示，请转到您的仓库设置，确保 GitHub 页面 发布源分支 设置为 gh-pages。

您的文档应该很快出现在 <username>.github.io/<repository>。

要在自定义域上发布您的网站，请参考 MkDocs 文档。

使用 MkDocs

如果您更喜欢手动部署项目文档，可以从包含 mkdocs.yml 文件的目录中调用以下命令：

mkdocs gh-deploy --force

这将构建您的文档并将其部署到您的仓库中的 gh-pages 分支。有关更多信息，请参见 MkDocs 文档中的此概述。有关参数的描述，请参见 该命令的文档。

GitLab Pages

如果您在 GitLab 上托管代码，可以通过使用 GitLab CI 任务运行器将其部署到 GitLab Pages。在您的仓库根目录中，创建一个名为 .gitlab-ci.yml 的任务定义，并复制粘贴以下内容：

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - ~/.cache/ # (1)!
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  1. 一些 Material for MkDocs 插件使用 缓存 来加速重复构建，并将结果存储在 ~/.cache 目录中。

现在，当新的提交推送到 默认分支（通常是 master 或 main）时，静态网站将自动构建和部署。提交并推送文件到您的仓库以查看工作流的实际运行。

您的文档默认不会发布在 <username>.gitlab.io/<repository> 下，因为 GitLab 17.4 1。但是，如果您更喜欢更简洁的 URL 结构，例如 <username>.gitlab.io/<repository>，则需要调整您的配置。

要从唯一域切换到传统的 URL 结构，请按照以下步骤操作：

  1. 定位您的仓库
  2. 在仓库菜单中转到 设置 › 页面。
  3. 在 唯一域设置 部分，取消选中 标记为 使用唯一域 的框。
  4. 点击 保存更改 以应用更新。

现在您可以在 <username>.gitlab.io/<repository> 下访问您的文档。

其他

由于我们无法覆盖所有可能的平台，我们依赖社区贡献的指南，解释如何将使用 Material for MkDocs 构建的网站部署到其他提供商：

  1. Gitlab 17.4 的发布说明 ↩