一直以来都在苦苦寻找一个能方便快捷的敲笔记和维护个人 Wiki 的方式,目前已经抛弃了之前搭建的 DokuWiki,开始使用 Emacs + Org-Mode 的管理模式,一段时间下来的感受就是“ Yeah!That's it.

why?

这部分写在最前面是为了让你了解到你是否真的需要 Wiki,或者仅仅只是一个简单的笔记软件。

笔记软件,例如 EverNote 、 WizNote 、 OneNote 、 各类云笔记都十分不错,主要用于记录单篇文章以及分类归档,这类软件的问题就是跨平台同步,启动是否流畅,排版是否美观,记录是否方便等;而且,常规的笔记软件的 Tag 标签系统相对比较单一。

相比之下 Wiki 系统更适合做系统性知识框架,其中有经典的 MediaWiki 系统,还有许许多多的静态 Wiki 系统,例如之前使用的 DokuWiki。然而,基于数据库的 MediaWiki 功能强大,但略显臃肿,插件众多,不适合个人维护。而静态 Wiki系统普遍基于单 HTML 文件,例如TiddlyWiki,加载速度快,但是这类系统大多生态环境较差,适合于爱折腾的朋友。一些电子书系统,如 GitBookReadtheDocs 可以用 Git 部署的,其基于 Markdown 和 Git 的书写模式原本非常适合作为个人 Wiki,但是现在这类系统越发臃肿,光光是在服务器上配置都是劳神费力,而且每一次撰写新条目和部署的复杂度也越来越令人难以接受。

你们可能已经看出了我口味相当的刁钻和需求相当的诡异,到目前整整用了5年的EverNote(现在基本成了废纸篓,真的懒得分类和摘取重点),期间也配合马克飞象做过一些文档书写,但还是对多平台多主机上的使用感到不习惯;在实验室使用 MediaWiki 写过一些文档,自己折腾过 DokuWiki,总的来说,我的需求是:多主机本地化编辑 > 跨平台 > 启动速度 > 配置复杂程度 > 编辑器,一番折腾于是便有了现在的这个Wiki。

wiki.png

what?

来看看我的Wiki

这是一个什么样的Wiki:

  • 跨平台/多主机同步(Git版本控制)
  • 本地编辑,在线发布;单 HTML 文件,也可以多个 HTML 组成更大的框架。
  • 配置小白也能操作,编辑器启动仅需1s。
  • 更胜于 Markdown 的标记语言,更强大的书写功能,你能更加专注的码字。

你需要什么:

  • Github 或者 自己配置的Gitlab/Gogs,甚至可以只是一个能 push/pull 的仓库
  • 一个带有 org-mode 编辑模式的 Emacs 编辑器(放心,Emacs 22之后所有版本都默认安装了org)
  • 学会一点点 org 书写格式
  • 想要页面样式更好看一点可以试试下面推荐的 ReadTheOrg Theme

很简单吧,如果只是本地发布,你甚至不需要部署 git ,因为 Emacs 能够生成包括 HTML 在内任何你想要的文件格式

how?

大致的流程如下:本地主机安装 Emacs 和 Git,创建 org-mode 文档,编辑好后可以选择直接生成 HTML。需要在线发布就 Push 到远程仓库,如果使用了 Github 类似的平台在 Push 到仓库后使用钩子自动部署到自己网站目录下。最后,切换平台/主机时记得 Clone 或者 Pull 一下,然后又可以愉快的开始编辑文档了。

gitwiki.png

Emacs+Org

上面提到的 Emacs 是一个功能强大的编辑器,你可以简单的将其理解为一个 Sublime,也可以将其理解为一个 Bash,甚至它也可以成为一个 IDE。更多 cool 的功能等待发掘,在此就不引起圣战了。

Org-mode 是 Emacs支持的内容分级显示的编辑模式,它的语法跟 Markdown 类似,如果你熟悉 MD 一定会很快上手。相比而言,org 除了一般的格式,还支持:文学编程、GTD、Todo 等,并且能够导出为各种格式。

Org-Mode强大的导出功能(无插件)orgexport.png

同时,Emacs还有许许多多 Git 插件,如Magit,git-emacs等,有了它们你可以在编辑完一次文档后只需按几下键盘就非常迅速的将其 Push 到远程仓库。

ReadTheOrg Theme

这是前面介绍中提到的主题样式,因为 Org 导出的是 Plain HTML,难免会看着不舒服。ReadTheOrg Theme 是参考 ReadtheDocs 生成的样式表,有了它你可以更清晰的阅读管理自己的Wiki。

使用方法很简单,只需要添加几行代码就行。将以下代码复制到.org文档头部,其中 css 和 js 建议下载到本地然后 push 到自己的仓库,这样可以保证在任何一个终端都可以看到相同样式。

# -*- mode: org; -*-
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="inc/css/htmlize.css"/>
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="inc/css/readtheorg.css"/>

#+HTML_HEAD: <script src="https://cdn.bootcss.com/jquery/2.1.3/jquery.min.js"></script>
#+HTML_HEAD: <script src="https://cdn.bootcss.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="inc/js/jquery.stickytableheaders.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="inc/js/readtheorg.js"></script>

Git Hooks

Git 钩子是指仓库环境改变时更改相应的项目环境的一种自动化进程,你可以用它来部署许多自动操作的步骤,例如我们在将文档 Push 到仓库后,可以用钩子将其自动部署到我们的网站下,这样每次打开我们的 Wiki 网站都能看到本地修改过的最新版文档。

首先到我们的网站目录下执行git clone的命令,将远程仓库中的文档pull到我们的网站下。

然后是为仓库部署 Git Hook。下面是我使用的 Post-receive 钩子,其部署在服务器上搭建的 Gogs 下self-wiki.git中。

#!/bin/bash
cd '你的网站下的wiki目录' || exit
unset GIT_DIR
git pull origin master
exec git-update-server-info

注意:此钩子只适用于 Git 仓库和网站位于同一个服务器,如果仓库托管在其他服务器上,如Github,可以配置 Web-Hook 钩子
参考:使用Github的webhooks进行网站自动化部署