Publish a Website with Material for MkDocs and GitHub Pages

template at https://github.com/csthenry

mkdocs new

$ 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

$ tree -a
.
├── docs
│   └── index.md
└── mkdocs.yml

Add GitHub Workflow

$ mkdir .github
$ cd .github
$ mkdir workflows
$ cd workflows
$ vim PublishMySite.yml

name: publish-site
on: # 在什么时候触发工作流
  push: # 在从本地master分支被push到GitHub仓库时
    branches:
      - master
  pull_request: # 在master分支合并别人提的pr时
    branches:
      - master
permissions:
  contents: write
jobs: # 工作流的具体内容
  deploy:
    runs-on: ubuntu-latest # 创建一个新的云端虚拟机 使用最新Ubuntu系统
    steps:
      - uses: actions/checkout@v4 # 先checkout到分支
      - uses: actions/setup-python@v5 # 再安装Python3和相关环境
        with:
          python-version: 3.x
      - run: pip install mkdocs-material # 使用pip包管理工具安装mkdocs-material
      - run: pip install mkdocs-glightbox # 灯箱插件（可选）
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支

$ tree -a
.
├── .github
│   ├── .DS_Store
│   └── workflows
│       └── PublishMySite.yml
├── docs
│   └── index.md
└── mkdocs.yml

Git and GitHub

git init

$ git init
$ git add .
$ git commit -m "init"

GitHub - New Repository

GitHub > New Repository

GitHub > Repository > Settings > Actions > General >

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

$ git remote add origin git@github.com:your_repo.git # change to your github repo
$ git branch -M main
$ git push -u origin main

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

Postscript

View your site at https://csthenry.github.io/.

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