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:
安装完成之后直接生成一个项目：
1 2 3 4 $ mkdocs new mysite [23:33:49] INFO - Creating project directory: mysiteINFO - Writing config file: mysite/mkdocs.ymlINFO - Writing initial docs: mysite/docs/index.md
看看都生成了啥：
1 2 3 4 5 6 7 8 $ cd mysite $ tree [23 :34 :59 ] . ├── docs │ └── index.md └── mkdocs.yml 1 directory, 2 files
默认生成了一个 yml 配置文件以及一个 默认的 markdown 文件。
看看 mkdocs 支持哪些命令：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 $ 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 documentation gh-deploy Deploy your documentation to GitHub Pages new Create a new MkDocs project serve Run the builtin development server
构建站点：
然后生成了一个 site 目录：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 $ 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.gz 7 directories, 28 files
可以看到 site 目录下就是站点的源码了，那么本地测试一下：
然后访问 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
1 2 3 cd wikigit remote rm origin git remote add origin https:
上面改成你自己的 wiki 地址（或者使用 ssh 的方式）
4 推送本地仓库 wiki 到远程 wiki
1 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 一样的内容：
那么如何编写你自己的 wiki 文章呢？
我们回到本地的 wiki 仓库：
注意，我的文档都放在了 source 目录下：
1 2 $ ls source git.md index.md other.md python.md rsync.md
所以你只需要删除我的 Markdown文档，把你的 Markdown 文档放到该目录，然后执行：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 $ 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: true history_buttons: true version: 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: 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: theme: custom_dir: mkdocs_windmill include_search_page: true name: null search_index_only: true static_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.git ba3b15e..4131 b86 master -> master [master 4131 b86] update mkdocs site 2 files changed, 1 insertion(+), 1 deletion(-) ############### git push done ###############
这个脚本的功能是根据 source 目录下的 Markdown 文档，更新 yaml 站点配置文件，然后生成站点源码，然后推送站点源码到 github 上。
如果执行出错，可以自行调试一下，一般问题不大。
博客首页引导栏添加 维基栏 这个过程就省略了。
The End wiki 站点搭建完毕，
Blog:
2020-09-20 于杭州By 史矛革
