发布您的网站¶

在git存储库中托管项目文档的好处是在推送新更改时自动部署它的能力。MkDocs 这让事情变得简单得可笑。

GitHub Pages¶

如果你已经在GitHub上托管你的代码，那么GitHub Pages肯定是发布项目文档的最便捷方式。它是免费的充电和设置非常容易。

with GitHub Actions¶

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

Material for MkDocsInsiders

name: ci # (1)!
on:
  push:
    branches:
      - master # (2)!
      - 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@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

你可以根据自己的喜好更改名称。
在某个时候，GitHub将master重命名为main。如果您的默认分支如果名为master，则可以安全地删除main，反之亦然。
存储cache_id环境变量，以便以后在缓存期间访问它创建key。该名称区分大小写，因此请确保将其与${{ env.cache_id }}对齐。
- --utc选项确保每个工作流运行器使用相同的时区。
- %V格式确保每周进行一次缓存更新。
- 您可以将格式更改为%F以进行每日缓存更新。
您可以阅读manual page以了解有关date命令的格式选项的更多信息。
Material for MkDocs插件使用caching来加速重复构建并将结果存储在.cache目录中。
这是安装更多MkDocs plugins或Markdown的地方在构建过程中使用带有pip的扩展：
```
pip install \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \
  ...
```

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@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@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache # (1)!
          restore-keys: |
            mkdocs-material-
      - run: apt-get install pngquant # (2)!
      - 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 }} # (3)!

Material for MkDocs插件使用caching来加速重复构建并将结果存储在.cache目录中。
只有当您想使用 built-in optimize plugin自动压缩图像。
记得将GH_TOKEN存储库密钥设置为您的值部署Insiders时，可以使用personal access token 使用GitHub secrets。

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

如果GitHub页面在几分钟后未显示，请转到以下设置您的存储库，并确保您的GitHub的publishing source branch 页面设置为gh-pages。

您的文档很快就会出现在<username>.github.io/<repository>中。

要在自定义域上发布您的网站，请参阅MkDocs documentation。

with MkDocs¶

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

mkdocs gh-deploy --force

这将构建您的文档并将其部署到分支 gh-pages在您的存储库中。请参阅this overview in the MkDocs documentation以获取更多信息。关于参数，请参阅the documentation for the command。

GitLab Pages¶

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

Material for MkDocsInsiders

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'

Material for MkDocs插件使用caching来加速重复构建并将结果存储在.cache目录中。

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

记得将GH_TOKEN存储库密钥设置为您的值部署Insiders时，可以使用personal access token 使用masked custom variables。
Material for MkDocs插件使用caching来加速重复构建并将结果存储在.cache目录中。

现在，当一个新的提交被推送到default branch（通常是master或 main），静态站点会自动构建和部署。承诺并推动将文件保存到您的存储库中，以查看正在运行的工作流。

您的文档未在<username>.gitlab.io/<repository>下发布默认情况下，自**GitLab 17.4** ¹以来。但是，如果您更喜欢更干净的URL 结构，如<username>.gitlab.io/<repository>，您需要调整您的配置。

要从唯一域切换到传统URL结构，请执行以下操作这些步骤：

查找您的存储库
转到存储库菜单中的**Settings › Pages**。
在**Unique domain settings**部分，**uncheck**标记的框
Use unique domain.
单击**Save changes**以应用更新。

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

其他¶

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

Release notes for Gitlab 17.4 ↩