Publish a Website with Material for MkDocs and GitHub Pages
template at https://github.com/csthenry
mkdocs new
Text Only |
---|
| $ 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
|
Text Only |
---|
| $ tree -a
.
├── docs
│ └── index.md
└── mkdocs.yml
|
Add GitHub Workflow
Text Only |
---|
| $ mkdir .github
$ cd .github
$ mkdir workflows
$ cd workflows
$ vim PublishMySite.yml
|
Text Only |
---|
| 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分支
|
Text Only |
---|
| $ tree -a
.
├── .github
│ ├── .DS_Store
│ └── workflows
│ └── PublishMySite.yml
├── docs
│ └── index.md
└── mkdocs.yml
|
Git and GitHub
git init
Text Only |
---|
| $ 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
Text Only |
---|
| $ 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.