发布网站¶
将网站托管在git
库中的最大好处是能够在推送新更改时自动部署它。MkDocs使得这一操作更加简单。
GitHub Pages¶
如果已经在GitHub上托管代码,那么使用GitHub Pages来发布网站再方便不过了。
使用GitHub Actions¶
使用GitHub Actions可以自动部署网站。在库的根目录下新建一个GitHub Actions workflow,比如:.github/workflows/ci.yml
,并粘贴入以下内容:
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”的任务定义,然后复制并粘贴以下内容:
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完成操作。