原文： https://rebootcat.com/2020/09/20/wiki/

why wiki

博客通常是用来记录一些完整的文章，每篇文章有一个主题。但是我想把平日里的一些笔记也记录到我的博客里，但笔记是零散的，随时的，不是完整的一个主题。所以打算构建一个 wiki 页面，专门用来存放我的笔记，wiki 页面类似于 维基百科的形式。

我的博客采用的是 hexo 构建的，如果打算 DIY 一个类似于 维基百科 的 wiki 页面的话，对于我来说，也许有点难度，毕竟我只会写简单的网页。那么有没有现成的方案或者替代的方案呢？

答案是有的，那就是 mkdocs。

mkdocs 使用

什么是 Mkdocs 呢？

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introduction below, then check the User Guide for more info.

mkdocs 是一个用 python 编写的静态站点生成工具，主要是用来编写项目文档，文档使用 Markdown 编写，只需要配合一个 YAML 配置文件，就能快速生成一个站点。

毫无疑问，对于我来说，它有以下几个优点：

• 使用 python 编写（说明有 DIY 的可能）
• 源文件使用 Markdown 编写
• 只需要一个 Yaml 文件，非常简单了
• 主题可选（当然目前来说不是特别多）

可以先看一下 我的wiki.

快速开始

可以参考官方文档：mkdocs.org，或者直接往下看：

首先安装 mkdocs:

$ pip install mkdocs

安装完成之后直接生成一个项目：

$ mkdocs new mysite                                                                    [23:33:49]
INFO    -  Creating project directory: mysite
INFO    -  Writing config file: mysite/mkdocs.yml
INFO    -  Writing initial docs: mysite/docs/index.md

看看都生成了啥：

$ cd mysite
$ tree                                                                                    [23:34:59]
.
├── docs
│   └── index.md
└── mkdocs.yml1 directory, 2 files

默认生成了一个 yml 配置文件以及一个 默认的 markdown 文件。

看看 mkdocs 支持哪些命令：

$ mkdocs -h                                                                               [23:36:21]
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...MkDocs - Project documentation with Markdown.Options:-V, --version  Show the version and exit.-q, --quiet    Silence warnings-v, --verbose  Enable verbose output-h, --help     Show this message and exit.Commands:build      Build the MkDocs documentationgh-deploy  Deploy your documentation to GitHub Pagesnew        Create a new MkDocs projectserve      Run the builtin development server

构建站点：

$ mkdocs build

然后生成了一个 site 目录：

$ tree                                                                                    [23:37:23]
.
├── docs
│   └── index.md
├── mkdocs.yml
└── site├── 404.html├── css│   ├── base.css│   ├── bootstrap.min.css│   └── font-awesome.min.css├── fonts│   ├── fontawesome-webfont.eot│   ├── fontawesome-webfont.svg│   ├── fontawesome-webfont.ttf│   ├── fontawesome-webfont.woff│   ├── fontawesome-webfont.woff2│   ├── glyphicons-halflings-regular.eot│   ├── glyphicons-halflings-regular.svg│   ├── glyphicons-halflings-regular.ttf│   ├── glyphicons-halflings-regular.woff│   └── glyphicons-halflings-regular.woff2├── img│   ├── favicon.ico│   └── grid.png├── index.html├── js│   ├── base.js│   ├── bootstrap.min.js│   └── jquery-1.10.2.min.js├── search│   ├── lunr.js│   ├── main.js│   ├── search_index.json│   └── worker.js├── sitemap.xml└── sitemap.xml.gz7 directories, 28 files

可以看到 site 目录下就是站点的源码了，那么本地测试一下：

$ mkdocs serve

然后访问 http://127.0.0.1:8000，能看到默认的站点了：

是不是超级超级简单？

那么这个是 mkdocs 最简单的使用，接下来分享下我的使用，经过了一些定制化，包括主题的选择，域名的绑定，站点的发布等。

使用 github pages 发布 wiki

我的博客使用了 github pages 进行托管（目前不是，目前已经迁移到香港虚拟空间），但是如何把上面 mkdocs 生成的站点源码和博客源码放到一起呢？

有很多方法，比如可以手动把 wiki 站点源码放到博客根目录下；

但其实 github pages 是可以支持多个站点的，不知道有没有同学还不知道？

简单来说，使用一个 github 账号，能创建一个 用户站点，格式为 <user>.github.io，比如我的博客源码仓库： smaugx.github.io;

但是除了一个用户站点之外，还能创建任意多个 普通站点，仓库名字任意，没有要求。

也就是说一个 github 账户其实是可以创建多个博客站点的。

关于如何创建一个普通站点，可以参考 github 官方文档：创建 GitHub Pages 站点.

或者往下看。

wiki 仓库设置

这里以我的 wiki 为例： https://github.com/smaugx/wiki，站点效果可以直接查看我的 wiki: https://rebootcat.com/wiki。

1 在 github 上创建一个仓库，命名为 wiki 或者其他的任意名字

2 克隆我的项目： git clone https://github.com/smaugx/wiki.git

3 更改仓库 remote-url 为你刚创建的 wiki 的 github url

cd wiki
git remote rm origin
git remote add origin  https://github.com/yourname/your-wiki.git

上面改成你自己的 wiki 地址（或者使用 ssh 的方式）

4 推送本地仓库 wiki 到远程 wiki

git push -u origin master

至此，你的 github 上应该有一个和我的 wiki 仓库一样的仓库了。

接下来讲一下怎么设置仓库。

5 首先去到刚创建好的 wiki 仓库 https://github.com/yourname/your-wiki

6 点击设置，往下拉到 GiHub Pages 配置项，选择 master 分支，选择 /docs 目录，然后点击 save 保存

7 上面一部之后，再次回到 Github Pages 配置项，找到下面的 Custom domain，填入你的域名或者 url 地址，比如我直接写了： http://rebootcat.com/wiki

8 不出意外，你就能正常访问了。

上面的前提当然是你已经有了个人博客，也就是已经有了一个命名为 <user>.github.io 的仓库了，不然是不会成功了，你要先创建一个这样的仓库。

编写wiki，更新 wiki

上面如果顺利的话，你能看到和我的 wiki 一样的内容：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-uQ6zJqkk-1601038121725)(https://cdn.jsdelivr.net/gh/smaugx/MyblogImgHosting_2/rebootcat/wiki/1.png)]

那么如何编写你自己的 wiki 文章呢？

我们回到本地的 wiki 仓库：

cd wiki

注意，我的文档都放在了 source 目录下：

$ ls source
git.md    index.md  other.md  python.md rsync.md

所以你只需要删除我的 Markdown文档，把你的 Markdown 文档放到该目录，然后执行：

$ python run.py
warning: found not support file type:.DS_Store
############### begin dump mkdocs.yml ###############
copyright: "Copyright \xA9 2020-2020 smaug"
docs_dir: source
extra:article_nav_bottom: truehistory_buttons: trueversion: v1.0.4
markdown_extensions:
- admonition
nav:
- Home: index.md
- python: python.md
- rsync: rsync.md
- git: git.md
- "\u5176\u4ED6": other.md
repo_url: https://github.com/smaugx/wiki
site_author: smaugx
site_description: "My Wiki | \u6797\u5915\u6C34\u5171"
site_dir: docs
site_name: "My Wiki | \u6797\u5915\u6C34\u5171"
site_url: http://rebootcat.com/wiki
theme:custom_dir: mkdocs_windmillinclude_search_page: truename: nullsearch_index_only: truestatic_templates:- 404.html############### update mkdocs.yml done ############################## begin mkdocs build ###############
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/smaug/centos7/SmaugDemo/wiki/docs
INFO    -  Documentation built in 0.18 seconds
############### mkdocs build done in dir:docs ############################## begin git push:git add --all . && git commit -m "update mkdocs site" && git push ###############
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 443 bytes | 443.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
To github.com:smaugx/wiki.gitba3b15e..4131b86  master -> master
[master 4131b86] update mkdocs site2 files changed, 1 insertion(+), 1 deletion(-)
############### git push done ###############

这个脚本的功能是根据 source 目录下的 Markdown 文档，更新 yaml 站点配置文件，然后生成站点源码，然后推送站点源码到 github 上。

如果执行出错，可以自行调试一下，一般问题不大。

博客首页引导栏添加 维基栏

这个过程就省略了。

The End

wiki 站点搭建完毕，

Blog:

• rebootcat.com

• email: linuxcode2niki@gmail.com

2020-09-20 于杭州
By 史矛革

总结

以上是生活随笔为你收集整理的使用 mkdocs 搭建个人 wiki 站点的全部内容，希望文章能够帮你解决所遇到的问题。

如果觉得生活随笔网站内容还不错，欢迎将生活随笔推荐给好友。