Build personal static wiki site via gollum-site

August 08 2014 , Category: git

Let’s start the article with a few background knowledge:

Purpose

Firstly, I just want to have a personal wiki to manage my knowledge. It should be easy to edit (use Markdown or something like it) the wiki. So I chose gollum as the wiki engine and it can fit my requirement perfectly.

Then I want to publish the wiki on the Internet just like my blog and other static sites. This may be easy with the gem named gollum-site, ‘cause it can generate HTML with the markdown source files.

With the service of GitHub pages, I can easily push contents to the Web.

Problems

However, these tools are not born for working together with each other.

  1. The contents I want to push to the remote and get hosted on GitHub is the HTML files inside _site folder, without the markdown resource created by gollum.

  2. Gollum is a “git-powered” wiki engine. That means after you created a gollum project locally, its folder should be a git repository. So we can’t just have gh-page branch in the _site folder which is generated by gollum-site.

  3. As we can just copy the contents within _site to another folder which can be on gh-pages, this may archive our goal. However, copy-paste is not a geek way to solve the problems and it’s dirty, too.

Best work flow

Spent time on Googling and as a result, I found a gist which can perfectly match my requirement.

Below is its introduction:

Setup GitHub Pages “gh-pages” branch as a subfolder within the “master” project on your local checkout.

Here comes the best work flow I summarized.

  1. Setup the project. Follow the process in the gist, create a gh-pages in your GitHub repository and checkout it in the _site folder (it should be empty before checkout).

  2. Edit wiki contents via gollum locally in your favoriate browser.

  3. Generate static resource by gollum-site.

  4. Change the current directory to _site and commit your changes, push to the remote at last.

There’re also many different ways to implement a personal wiki such as vim-wiki and so on, however, the work flow I introduced is simple and efficient for me. It is also available to create a bash/zsh script to automatically complete the work flow.

–EOF–

支持作者 | Article licensed under CC BY-NC-SA 4.0