发布网站¶

将网站托管在git库中的最大好处是能够在推送新更改时自动部署它。MkDocs使得这一操作更加简单。

GitHub Pages¶

如果已经在GitHub上托管代码，那么使用GitHub Pages来发布网站再方便不过了。

使用GitHub Actions¶

使用GitHub Actions可以自动部署网站。在库的根目录下新建一个GitHub Actions workflow，比如：.github/workflows/ci.yml，并粘贴入以下内容：

Material for MkDocs

name: ci
on:
  push:
    branches:
      - master
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

内测版本

name: ci
on:
  push:
    branches:
      - master
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.fork == false
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - 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 }}

此时，当一个新的提交推送到master或main时，我们的静态网站的内容将自动生成并完成部署。可以尝试推送一个提交来查看GitHub Actions的工作状况。

网站将在不久后部署到<username>.github.io/<repository>。

注意，如果是部署的内测版本，记得在personal access token中添加GH_TOKEN的环境变量值,可以使用secrets完成操作。

使用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
  only:
    - master
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public

内测版本

image: python:latest
pages:
  stage: deploy
  only:
    - master
  script:
    - pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public

此时，当一个新的提交推送到master时，静态网站的内容将自动生成并完成部署。提交并推送文件到库就能看到效果了。

网站将在不久后部署到<username>.gitlab.io/<repository>。

注意，如果是部署的内测版本，记得在personal access token中添加GH_TOKEN的环境变量值,可以使用masked custom variables完成操作。