Mkdocs-Wcowin/快速开始.md

推荐看下这个视频：

How to set up Material for MkDocs by @Wcowin – 10m – 用MKdocs构建一个博客网站.

---

一、准备工作

1.下载Github Desktop{target=“_blank”}

2.有一个GitHub账号​​​​​​​(有手就行)

---

二、Creating your site

参考教程：

利用mkdocs部署静态网页至GitHubpages（更新版）{target=“_blank”}

与其他教程不同，我首先建议先在Github创建一个名为你的名字+github.io的仓库

然后打开github Desktop 克隆到本地

打开Wcowin.github.io目录进入终端依次运行:

pip install mkdocs-material
mkdocs new mkdocs-site

出现下图的几个文件

!!! tip

这里建议把**mkdocs-site**文件里的东西全部剪切出来到**Wcowin.github.io**文件里  
![img](https://s1.imagehub.cc/images/2024/02/02/b4a5ac989f1f390573a85bad8c80f49b.png)

Wcowin.github.io是克隆到本地的仓库（里面包含docs,yml文件等等），docs文件下是以后网站的内容，mkdocs.yml是配置文件（配置主题，目录，插件等）

你在这个目录下写的任何东西都可以通过Github Desktop 上传到github上

执行下面的代码添加一个GitHub Workflow

---

mkdir .github
cd .github
mkdir workflows
cd workflows
vim ci.yml

进入.github/workflows/ci.yml，然后复制并粘贴以下内容：

name: ci 
on:
  push:
    branches:
      - master 
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

到这里先检查一下你的目录结构
目录树状图:

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

重点来了 Github仓库setings/Actions/General 勾选这两项

三、配置完善

打开mkdocs.yml

把以下的内容输入进去（最简单最基础的配置）

site_name: 网站名字
site_url: 网站链接
site_author: 你的名字
theme:
  name: material #主题

详细mkdocs.yml配置见Changing the colors - Material for MkDocs

---

在下方终端运行可以在浏览器看到实时网站

mkdocs serve

这个网站就算是初步建好了

最后去github Desktop上传到github 上图可以看到，我上传了Wcowin.github.io文件夹，这个文件夹里面包含了mkdocs.yml和docs文件夹(mkdocs-site文件夹现在没有东西，可以删除)

！！！重点
去仓库的setings/pages选择下图示意的路径

等待一会网址就出来了¹

你的网站网址就是：​

https://你github的名字.github.io/
因为我绑定了域名所以网址是：https://wcowin.work/

下次谈谈网站的mkdocs.yml具体配置

四、参考资料

1. MkDocs官网
2. MkDocs中文文档
3. Material for MkDocs
4. Mkdocs 配置和使用
5. Deploy MkDocs

---

1. 于2025.2.19重写此文 ↩︎