关于 ¶

本wiki是基于Mkdocs一个基于python的开源文档（wiki）发布系统。

基础用法 ¶

编写 ¶

文档可写在：docs/xxx/xxx.md 中。

在根目录的mkdocs.yml的 nav 节点中添加菜单目录即可

运行 ¶

因为本文档是基于python的 mkdocs项目，随意拉取代码后第一步就是按照依赖

拉取文档

# 不需要指定目录
git clone https://github.com/yicheng2110/wubing-wiki.git

# 指定目录拉取
git clone https://github.com/yicheng2110/wubing-wiki.git "D:/code/wiki"

按照依赖 (最后基于虚拟环境：python -m venv .venv)

pip install -r requirements.txt

运行本地环境

mkdir serve

发布 ¶

自定义部署（生成html）

mkdocs build

这将创建一个名为site的新目录。看一下该目录的情况：

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----       2025/3/10  下午 02:37                about
d-----       2025/3/10  下午 02:37                assets
d-----       2025/3/10  下午 02:37                search
-a----       2025/3/10  下午 02:37          15513 404.html
-a----       2025/3/10  下午 02:37          15789 index.html
-a----       2025/3/10  下午 02:37            109 sitemap.xml
-a----       2025/3/10  下午 02:37            127 sitemap.xml.gz

如果自定义部署子直接把site目录的所有文件上传到指定目录即可

使用github 的pages 来部署项目

mkdocs gh-deploy

在本地拉取github文档后，如果对文章进行进行变更以后，可以直接执行该命令直接部署pages

常见问题 ¶

如果Pages使用了自定义域名则实行以下步骤 ¶

a. 添加cname dns记录，比如：将wiki.20211001.xyz记录cname到你得github主页地址：github.com/yicheng2110

b. 在master分支docs目录中创建一个CNAME文件，文件内容就是自定义域名地址: wiki.20211001.xyz 不需要加http,https协议头

如果在github的网页操作了什么配置。可能会导致仓库发生了改变。、¶

此时可能执行mkdocs gh-deploy命令可能会失效我这边的解决方案为，本地git检出到gh-pages分支，且重新拉取gh-pages仓库，大概率会有新的代码。此时再切换到master分支中，执行mkdocs gh-deploy命令记录即可操作成功。