发布您的网站¶

¥Publishing your site¶

将项目文档托管在git仓库中的好处在于，当新的变更被推送时，它能够自动部署。MkDocs 让这一切变得异常简单。

¥The great thing about hosting project documentation in a git repository is the ability to deploy it automatically when new changes are pushed. MkDocs makes this ridiculously simple.

GitHub 页面¶

¥GitHub Pages¶

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

¥If you're already hosting your code on GitHub, GitHub Pages is certainly the most convenient way to publish your project documentation. It's free of charge and pretty easy to set up.

使用 GitHub Actions¶

¥with GitHub Actions¶

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

¥Using GitHub Actions you can automate the deployment of your project documentation. At the root of your repository, create a new GitHub Actions workflow, e.g. .github/workflows/ci.yml, and copy and paste the following contents:

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以实现每日缓存更新。您可以阅读手册页，了解有关date命令格式选项的更多信息。
一些 Material for MkDocs 插件使用缓存来加速重复构建，并将结果存储在~/.cache目录中。
¥The --utc option makes sure that each workflow runner uses the same time zone.
这是安装更多MkDocs 插件或 Markdown 扩展的地方，其中pip将在构建期间使用：
¥The %V format assures a cache update once a week.
```
pip install \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \
  ...
```
```
pip install \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \
  ...
```
pip install \ mkdocs-material \ mkdocs-awesome-pages-plugin \ ... pip 安装 \ 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 插件使用缓存来加速重复构建，并将结果存储在~/.cache目录中。
¥You can change the format to %F to have daily cache updates.
只有当您想使用内置优化插件自动压缩图像时，才需要此步骤。
部署Insiders时，请记住将GH_TOKEN存储库机密设置为您的个人访问令牌的值，这可以使用GitHub 机密来完成。

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

¥You can change the name to your liking.

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

¥At some point, GitHub renamed master to main. If your default branch is named master, you can safely remove main, vice versa.

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

¥Store the cache_id environmental variable to access it later during cache key creation. The name is case-sensitive, so be sure to align it with ${{ env.cache_id }}.

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

¥You can read the manual page to learn more about the formatting options of the date command.

使用 MkDocs¶

¥with MkDocs¶

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

¥Some Material for MkDocs plugins use caching to speed up repeated builds, and store the results in the ~/.cache directory.

mkdocs gh-deploy --force

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

¥This is the place to install further MkDocs plugins or Markdown extensions with pip to be used during the build:

GitLab 页面¶

¥GitLab Pages¶

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

¥Some Material for MkDocs plugins use caching to speed up repeated builds, and store the results in the ~/.cache directory.

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 插件使用缓存来加速重复构建，并将结果存储在~/.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'

部署Insiders时，请记住将GH_TOKEN存储库机密设置为您的个人访问令牌的值，这可以使用屏蔽自定义变量来完成。
一些 Material for MkDocs 插件使用缓存来加速重复构建，并将结果存储在~/.cache目录中。

现在，当新的提交推送到默认分支（通常是master或main ）时，静态站点将自动构建并部署。提交并将文件推送到您的代码库，即可查看实际的工作流程。

¥This step is only necessary if you want to use the built-in optimize plugin to automatically compress images.

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

¥Remember to set the GH_TOKEN repository secret to the value of your personal access token when deploying Insiders, which can be done using GitHub secrets.

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

¥Now, when a new commit is pushed to either the master or main branches, the static site is automatically built and deployed. Push your changes to see the workflow in action.

找到您的存储库
¥Some Material for MkDocs plugins use
转到存储库菜单中的“设置”>“页面” 。
在唯一域名设置部分中，取消选中标有
使用唯一域名。
¥Locate Your Repository
单击“保存更改”以应用更新。
¥Go to Settings › Pages in the repository menu.

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

¥If the GitHub Page doesn't show up after a few minutes, go to the settings of your repository and ensure that the publishing source branch for your GitHub Page is set to gh-pages.

其他¶

¥Other¶

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

¥Your documentation should shortly appear at <username>.github.io/<repository>.

Cloudflare 页面
¥In the
Fly.io
¥Use unique domain
Netlify
¥Click
Scaleway
¥ Cloudflare Pages

Gitlab 17.4 发行说明 ↩
¥ Fly.io