lord63's blog

Set up your own wiki

2014-10-14

为什么要有自己的 wiki

首先来说说我自己的原因，因为在使用电脑的过程中总是会遇到各种各样的问题，而你可能需要通过一定时间的 Google，查看很多网页，尝试着去解决它。而如果过了一段时间后可能又再一次遇到这样类似的问题，可能你就只会记得些许关键词而又要查看很多网页才找到原来解决方法的出处。次数多了以后，我就开始要解决这个问题了。起先我是放在一个文本里，然后记录了一些问题和解决事项。但感觉还不是很好。我装机的详细的软件列表和具体软件的详细配置之前也是放在单独的文本中的。而你有了自己的 wiki 以后，你可以时不时的记录下碰到的问题和解决方法，下次碰到你就可以直接去你的 wiki 查找。

除了上面说的有了 wiki 可以方便总结和查找，还可以对你自己的知识进行总结和梳理。单独的知识点可能逐渐会连成一片，而且自己归纳的总是会印象比较深。

为什么我选择 simiki 来管理自己的 wiki

Markdown 写作
支持本地预览，而且我认为本地其实用的比你部署的次数远远的多
它是用 python 写的，意味着我也许可以看看源码，修改来符合自己的习惯
生成 html，方便部署

如何部署 simiki 来管理自己的 wiki

目前我使用 Github 来托管我的 wiki，使用 Project Pages 来托管静态文件，即在 Github 新开一个 repo， master 分支放源代码和 markdown 文件，gh-pages 放 simiki 的 ouptut 文件夹中的静态文件。好处有:

使用 Git 进行版本控制
Github 是良好的托管的地方，可以当作备份的地方, 一个 repo 就可以了
Project Pages 很方便，也支持 custom domain

一般的我的 wiki 的 workflow：

    You're editing your wiki, then preview at local to ensure it is fine
    $ simiki generate
    $ simiki preview

    Everything looks good, it's time for committing the changes
    $ git add XXX
    $ git commit -v

    Push the commmits to your github repo
    $ git push

    But how can we update our wiki website? With the help of ghp-import
    (use `pip install ghp-import` to install it), one command is enough!
    $ ghp-import -p output

Tips

我目前是使用着 Project Pages + custom domain 的，如果你没有自己的域名或者不想使用什么，那么当你使用 Project Pages 时，注意在 _config.yml 中设置 root: REPO_NAME, 当你本地预览的时候，请使用 simiki preview --ignore-root. 访问你的 wiki 的在线地址为 https://USERNAME.github.io/REPO_NAME. 而使用 custom doman 则不用设置 root， preview 也不需要什么，访问地址为你自定义的域名。然后记得在域名服务商那里修改 DNS Record，增加一条 CNAME 记录，指向 USERNAME.github.io
关于 ghp-import，当你第一次使用时，只需要运行 ghp-import -p output 就可以了，其他的一切它都会帮你做的，你不用手动做任何事情，以后每次更新网站的时候运行同样的命令就行了。注意以上命令的使用场景为 Project Pages, 使用 User Pages 请将命令改成 ghp-import -b master -p output。你可能感觉每次打都很麻烦，我目前的情况是经常性地 push 到 master 分支，而频率十分低地 push 到 gh-page 分支，因为我本地的预览次数远远高于去看实际部署的（这个估计只有自己电脑不在身边时可能用到）。
关于本地预览，最开始我是笨笨地开两个标签，一个开 server，一个时不时 generate，后来我自己用 pyinotify 写了个快糙猛的 watch.py，监视 content 目录，有变化时 generate 一下。也可以用 FreeFileSync 的 RealtimeSync，也是一样，有变动 generate 一下。
关于 preview. 你可以使用 supervisor 来帮你更加方便地实现。这样的话，它就会在后台有个简单的服务器，而且开机启动，配合上面一点，那么你可以专心地编辑你自己的 wiki 了。具体的我的做法是这样子的:
1. 安装, sudo apt-get install supervisor
2. 配置，在 /etc/supervisor/conf.d 下新建一个配置文件 wiki.conf，内容可以是这样:
```
[program:wiki]
command = python -m SimpleHTTPServer 1234
directory = /home/lord63/code/wiki.lord63.com/output
autostart = true
autorestart = true
```
3. 启动并查看
```
$ sudo supervisorctl update
$ sudo supervisorctl status
```
此时你应该可以看到你的 "wiki" 已经跑起来了

Set up your own wiki

为什么要有自己的 wiki

为什么我选择 simiki 来管理自己的 wiki

如何部署 simiki 来管理自己的 wiki

Tips

Futher reading