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 史矛革