Build personal static wiki site via gollum-site

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

• gollum: Git-powered wiki engine which provide users a local front-end to edit wiki with various formats (such as GFM, a.k.a, GitHub Flavored Markdown).

• gollum-site: Another Gem written in Ruby. We can consider it a static site generator for gollum. Its function is just like the widely used generator whose name is Jekyll.

• GitHub Pages: Official github service for hosting static web sites.

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–