发布你的网站

将 MkDocs 项目托管在 Git 仓库的最大优势之一是可以自动部署文档。Material for MkDocs 对部署进行了高度简化。

GitHub Pages 发布

自动部署（推荐）-GitHub Actions

使用 GitHub Actions 自动构建并发布网站：
在项目根目录下新建 .github/workflows/ci.yml，示例配置如下：

name: ci
on:
  push:
    branches:
      - main  # 或 master，根据你的默认分支设置
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure 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: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

提交代码后，GitHub Actions 会自动构建并将生成的网站发布到 gh-pages 分支。
补充说明
- 默认访问地址：https://<用户名>.github.io/<仓库名>
- 若页面未显示，需在 GitHub 仓库 Settings › Pages 中设置 Source 为 gh-pages 分支
- 可自定义域名，具体见 MkDocs 官方文档

1.  You can change the name to your liking.

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

3.  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 }}`.

    - The `--utc` option makes sure that each workflow runner uses the same time zone.
    - The `%V` format assures a cache update once a week.
    - You can change the format to `%F` to have daily cache updates.

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

4.  Some Material for MkDocs plugins use [caching] to speed up repeated
    builds, and store the results in the `.cache` directory.

5.  This is the place to install further [MkDocs plugins] or Markdown
    extensions with `pip` to be used during the build:

    ``` sh
    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@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)!

手动部署-MkDocs

如果你不使用 CI/CD，可手动运行以下命令发布：

mkdocs gh-deploy --force

此命令会自动构建项目，并将内容推送到 gh-pages 分支。

GitLab Pages 发布

在 GitLab 项目的根目录中创建.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/
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

默认部署位置可能不是 username.gitlab.io/repository，如需使用传统结构，可前往 Settings › Pages 关闭“Use unique domain”。

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - .cache/
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

其他平台部署

Material for MkDocs 也可部署到如下平台，社区提供了对应教程：
- Cloudflare Pages
- Flyio
- Netlify
- Scaleway