Setup Github Page, Jekyll, and Jekyll Bootstrap

gistfile1.md

My original plan is to setup a good viewing environment for markdown files (analyzing results produced by some template engine). No blog functions are needed. However, it turns out to be tedious and not as useful as expected.

To setup Ruby, basically following this link is fine. Note that rails (or at least node.js) is needed. Pure ruby is not enough.

To setup Jekyll, following this link. After installation, running

$ bundle exec jekyll serve

will give you html parsed from markdown in _site/ folder. Also, github can successfully show the html (upload of _site/ is not needed, only Gemfile and _config.xml are probably useful). index.md in the root folder will turn to index.html in the generated folder _site. Although the completely manual index.md may work, since the main propose for Jekyll is for blogs, it has strict document structure which is hard to use for no blogging propose. Also, there's no theme/css for the html file.

To have the theme for markdown files, it seems that the easiest way is to use Jekyll Bootstrap and its themes. However, (1) Jekyll Bootstrap is even more strict for document structure, (2) its parser cannot parse

` ` `java
...
` ` `

(3) its table format are not easy to use (that should be possible to solve by manually change the css files, but I'm lazy), and (4) it does not support images with relative link. Also, by uploading the Jekyll Bootstrap files to github, seems it cannot load the theme. So I give up trying it.

P.S If I accidentally killed Jekyll using ctrl-Z (I should use ctrl-C), system will complain

jekyll 2.4.0 | Error:  Address already in use - bind(2) for 0.0.0.0:4000

In that case,

$ lsof -wni tcp:4000
COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
jekyll  30300 beta    8u  IPv4 201361      0t0  TCP *:4000 (LISTEN)
$ kill -9 30300

will solve the problem.