跳转至

mkdocs + GitHub 搭建文档网站

基础流程

  • 安装 Python 依赖包
mkdocs==1.2.2
mkdocs-material==7.1.11
mkdocs-material-extensions==1.0.1
mike==1.0.1
  • 新建本地项目 myblog
mkdocs new myblog

  • 新建GitHub项目 myblog 并 clone 到本地

  • 在 clone 下来的 myblog 中移入本地文件夹 myblog 的内容，并 push 到远程仓库

  • 新建 gh-pages 分支

git checkout -b gh-pages
  • 在 GitHub 项目文件夹下编译文件
mkdocs build
  • 删除除site之外的文件并将site文件夹的文件更新到root中
  • 将项目文件夹更新到 gh-pages 分支，此时查看 GitHub myblog 项目的 setting Pages 即可以看到对应网页地址

利用 GitHub Action 完成自动化 mkdocs 编译

  • 点击 GitHub myblog 的 Action，新建一个 simple workflow

image

  • 修改 yaml 文件
# This is a basic workflow to help you get started with Actions

name: public site

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3

      - name: Install mkdocs
        run: |
          python -m pip install mkdocs==1.2.2
          python -m pip install mkdocs-material==7.1.11
          python -m pip install mkdocs-material-extensions==1.0.1
          python -m pip install mike==1.0.1

      - name: Create html
        run: mkdocs build

      - name: Public
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
Back to top