跳转至

基于Github Pages部署MkDocs个人主页

一份开箱即用、自底向上的MkDocs部署指南

我们提过基于Github Actions部署mdBook网页的方式，这里我们讲解如何利用Github Pages部署MkDocs个人主页。

仔细回顾会发现，我们在mdBook教程里讲的顺序是 “从远端用template -> 本地客制化 -> push”，有一点“自顶向下”的意味。

为了使讲解更加深入浅出，我们在这里介绍MkDocs部署时，顺序是 “本地初始化仓库 -> 本地兼顾远程(CI) -> push”，遵守“自底向上”的哲学。

mkdocs new

Bash
1
2
3
4
5
mkdocs new mkdocs-site
INFO     -  Creating project directory: mkdocs-site
INFO     -  Writing config file: mkdocs-site/mkdocs.yml
INFO     -  Writing initial docs: mkdocs-site/docs/index.md
cd mkdocs-site
Bash
1
2
3
4
5
tree -a
.
├── docs
│   └── index.md
└── mkdocs.yml

Add GitHub Workflow

Bash
1
2
3
4
5
mkdir .github
cd .github
mkdir workflows
cd workflows
vim PublishMySite.yml
YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
name: publish site
on: # 在什么时候触发工作流
  push: # 在从本地main分支被push到GitHub仓库时
    branches:
      - main
  pull_request: # 在main分支合并别人提的pr时
    branches:
      - main
jobs: # 工作流的具体内容
  deploy:
    runs-on: ubuntu-latest # 创建一个新的云端虚拟机 使用最新Ubuntu系统
    steps:
      - uses: actions/checkout@v2 # 先checkout到main分支
      - uses: actions/setup-python@v2 # 再安装Python3和相关环境
        with:
          python-version: 3.x
      - run: pip install mkdocs-material # 使用pip包管理工具安装mkdocs-material
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支
Bash
1
2
3
4
5
6
7
8
9
tree -a
.
├── .github
│   ├── .DS_Store
│   └── workflows
│       └── PublishMySite.yml
├── docs
│   └── index.md
└── mkdocs.yml

Git and GitHub

In your local folder:

Bash
1
2
3
git init
git add .
git commit -m "init"

Now visit github:

GitHub > New Repository

GitHub > Repository > Settings > Actions > General >

  • Actions permissions: Allow all actions and reusable workflows
  • Workflow permissions: Read and write permissions
  • Click Save

Back to local folder:

Bash
1
2
3
git remote add origin git@github.com:root-hbx/mkdocs-site.git # change to your github repo
git branch -M main
git push -u origin main

Follow and see what's happening in github:

GitHub > Repository > Settings > Pages > Source > gh-pages > Click Save

Postscript

Modify your markdown files in docs/, make a new commit and push your site to GitHub. GitHub will automatically publish the newest contents.