发布您的站点

在git存储库中托管项目文档的一个很棒的功能是在推送新更改时自动部署。MkDocs 使这一过程非常简单。

GitHub Pages

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

使用 GitHub Actions

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

Material for MkDocs

name: ci # (1)!
on:
  push:
    branches:
      - master # (2)!
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material # (4)!
      - run: mkdocs gh-deploy --force

您可以根据自己的喜好更改名称。
GitHub在某个时间点将master重命名为main。如果您的默认分支名为master，您可以安全地删除main，反之亦然。
存储cache_id环境变量以在稍后的缓存key创建过程中使用。名称区分大小写，所以请确保与${{ env.cache_id }}保持一致。
- --utc选项确保每个工作流运行器使用相同的时区。
- %V格式确保每周更新一次缓存。
- 您可以将格式更改为%F以每天更新缓存。
您可以阅读手册页以了解date命令的更多格式选项。
这是安装其他MkDocs插件或Markdown扩展的地方，使用pip进行构建时使用：
```
pip install \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \
  ...
```

Insiders

name: ci
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    if: github.event.repository.fork == false
    steps:
      - uses: actions/checkout@v3
      - 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: apt-get install pngquant # (1)!
      - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
      - run: mkdocs gh-deploy --force
env:
  GH_TOKEN: ${{ secrets.GH_TOKEN }} # (2)!

仅在您想要使用内置的优化插件自动压缩图像时才需要此步骤。
在部署Insiders时，请记得将GH_TOKEN环境变量设置为您的个人访问令牌的值，可以使用GitHub secrets进行设置。

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

如果几分钟后 GitHub 页面没有显示出来，请转到存储库的设置，并确保您的 GitHub 页面的发布源分支设置为gh-pages。

您的文档应该很快出现在<用户名>.github.io/<存储库>上。

使用 MkDocs

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

mkdocs gh-deploy --force

GitLab Pages

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

Material for MkDocs

image: python:latest
pages:
  stage: deploy
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Insiders

image: python:latest
pages:
  stage: deploy
  script: # (1)!
    - pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

在部署Insiders时，请记得将GH_TOKEN环境变量设置为您的个人访问令牌的值，可以使用掩码自定义变量进行设置。

现在，当新的提交被推送到master分支时，静态站点将自动构建和部署。提交并推送文件到您的存储库以查看工作流程。

您的文档应该很快出现在<用户名>.gitlab.io/<存储库>上。

其他

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

企业支持

如果您的组织正在使用Material for MkDocs，并且需要帮助，例如缩短构建时间、提高性能或确保合规性，请联系我们讨论我们的企业支持服务。我们乐意提供帮助！