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

why wiki

博客通常是用來記錄一些完整的文章，每篇文章有一個(gè)主題。但是我想把平日里的一些筆記也記錄到我的博客里，但筆記是零散的，隨時(shí)的，不是完整的一個(gè)主題。所以打算構(gòu)建一個(gè) wiki 頁面，專門用來存放我的筆記，wiki 頁面類似于 維基百科的形式。

我的博客采用的是 hexo 構(gòu)建的，如果打算 DIY 一個(gè)類似于 維基百科 的 wiki 頁面的話，對(duì)于我來說，也許有點(diǎn)難度，畢竟我只會(huì)寫簡(jiǎn)單的網(wǎng)頁。那么有沒有現(xiàn)成的方案或者替代的方案呢？

答案是有的，那就是 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 是一個(gè)用 python 編寫的靜態(tài)站點(diǎn)生成工具，主要是用來編寫項(xiàng)目文檔，文檔使用 Markdown 編寫，只需要配合一個(gè) YAML 配置文件，就能快速生成一個(gè)站點(diǎn)。

毫無疑問，對(duì)于我來說，它有以下幾個(gè)優(yōu)點(diǎn)：

• 使用 python 編寫（說明有 DIY 的可能）
• 源文件使用 Markdown 編寫
• 只需要一個(gè) Yaml 文件，非常簡(jiǎn)單了
• 主題可選（當(dāng)然目前來說不是特別多）

可以先看一下 我的wiki.

快速開始

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

首先安裝 mkdocs:

$ pip install mkdocs

安裝完成之后直接生成一個(gè)項(xiàng)目：

$ 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

默認(rèn)生成了一個(gè) yml 配置文件以及一個(gè) 默認(rèn)的 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

構(gòu)建站點(diǎn)：

$ mkdocs build

然后生成了一個(gè) 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 目錄下就是站點(diǎn)的源碼了，那么本地測(cè)試一下：

$ mkdocs serve

然后訪問 http://127.0.0.1:8000，能看到默認(rèn)的站點(diǎn)了：

是不是超級(jí)超級(jí)簡(jiǎn)單？

那么這個(gè)是 mkdocs 最簡(jiǎn)單的使用，接下來分享下我的使用，經(jīng)過了一些定制化，包括主題的選擇，域名的綁定，站點(diǎn)的發(fā)布等。

使用 github pages 發(fā)布 wiki

我的博客使用了 github pages 進(jìn)行托管（目前不是，目前已經(jīng)遷移到香港虛擬空間），但是如何把上面 mkdocs 生成的站點(diǎn)源碼和博客源碼放到一起呢？

有很多方法，比如可以手動(dòng)把 wiki 站點(diǎn)源碼放到博客根目錄下；

但其實(shí) github pages 是可以支持多個(gè)站點(diǎn)的，不知道有沒有同學(xué)還不知道？

簡(jiǎn)單來說，使用一個(gè) github 賬號(hào)，能創(chuàng)建一個(gè) 用戶站點(diǎn)，格式為 <user>.github.io，比如我的博客源碼倉庫： smaugx.github.io;

但是除了一個(gè)用戶站點(diǎn)之外，還能創(chuàng)建任意多個(gè) 普通站點(diǎn)，倉庫名字任意，沒有要求。

也就是說一個(gè) github 賬戶其實(shí)是可以創(chuàng)建多個(gè)博客站點(diǎn)的。

關(guān)于如何創(chuàng)建一個(gè)普通站點(diǎn)，可以參考 github 官方文檔：創(chuàng)建 GitHub Pages 站點(diǎn).

或者往下看。

wiki 倉庫設(shè)置

這里以我的 wiki 為例： https://github.com/smaugx/wiki，站點(diǎn)效果可以直接查看我的 wiki: https://rebootcat.com/wiki。

1 在 github 上創(chuàng)建一個(gè)倉庫，命名為 wiki 或者其他的任意名字

2 克隆我的項(xiàng)目： git clone https://github.com/smaugx/wiki.git

3 更改倉庫 remote-url 為你剛創(chuàng)建的 wiki 的 github url

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

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

4 推送本地倉庫 wiki 到遠(yuǎn)程 wiki

git push -u origin master

至此，你的 github 上應(yīng)該有一個(gè)和我的 wiki 倉庫一樣的倉庫了。

接下來講一下怎么設(shè)置倉庫。

5 首先去到剛創(chuàng)建好的 wiki 倉庫 https://github.com/yourname/your-wiki

6 點(diǎn)擊設(shè)置，往下拉到 GiHub Pages 配置項(xiàng)，選擇 master 分支，選擇 /docs 目錄，然后點(diǎn)擊 save 保存

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

8 不出意外，你就能正常訪問了。

上面的前提當(dāng)然是你已經(jīng)有了個(gè)人博客，也就是已經(jīng)有了一個(gè)命名為 <user>.github.io 的倉庫了，不然是不會(huì)成功了，你要先創(chuàng)建一個(gè)這樣的倉庫。

編寫wiki，更新 wiki

上面如果順利的話，你能看到和我的 wiki 一樣的內(nèi)容：

[外鏈圖片轉(zhuǎn)存失敗,源站可能有防盜鏈機(jī)制,建議將圖片保存下來直接上傳(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

所以你只需要?jiǎng)h除我的 Markdown文檔，把你的 Markdown 文檔放到該目錄，然后執(zhí)行：

$ 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 ###############

這個(gè)腳本的功能是根據(jù) source 目錄下的 Markdown 文檔，更新 yaml 站點(diǎn)配置文件，然后生成站點(diǎn)源碼，然后推送站點(diǎn)源碼到 github 上。

如果執(zhí)行出錯(cuò)，可以自行調(diào)試一下，一般問題不大。

博客首頁引導(dǎo)欄添加 維基欄

這個(gè)過程就省略了。

The End

wiki 站點(diǎn)搭建完畢，

Blog:

• rebootcat.com

• email: linuxcode2niki@gmail.com

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

總結(jié)

以上是生活随笔為你收集整理的使用 mkdocs 搭建个人 wiki 站点的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。