Initialize the First Blog

This is my first blog that is generated using org-mode, jekyll and is published on GitHub. I made this page following the instructions on org-jekyll.

1 Install necessary softwares org-mode in emacs, jekyll.

Note that the built-in org-mode in emacs might be outdated, the best solution is to remove the built-in org-mode and reinstall it from the package manager via M-x list-packages. Jekyll can be installed through RubyGem. On my OSX, the ruby and gem are preinstalled, so gem install jekyll works for me.

2 Initialize the web folder by jekyll.

As my final goal is posting the blog to GitHub, the working folder of my blog is xiaoliuai.github.io. 

jekyll new xiaoliuai.github.io
cd xiaoliuai.github.io
jekyll serve

Then you can see the portal page by opening localhost:4000 in your web browser.

Now I would like to introudce the directory hierarchy of jekyll. Since I will move to octopress, which is a wrapper of jekyll with different directory setting, I just introduce the essential part to make the things work. 

xiaoliuai.github.io/
-- _posts/
-- _sites/
...

Two main directories need special attention, that are, _posts and _sites. The first folder contains the source files, which are markdown file, html file, etc. as input for jekyll; the second folder contains the generated static server pages. All the project should be uploaded to github to be displayed where the index.html file is the portal of web site. The GitHub Pages understand this directory configuration and will automatically display the contents in _sites.

3 From org-mode to jekyll

3.1 Configuration of emacs org setting

("blog-org"
 :base-directory "~/Emacs/org/blog"
 :base-extension "org"

 :publishing-directory "~/WorkSpace/xiaoliuai.github.io/"
 :recursive t
 :publishing-function org-html-publish-to-html
 :headline-levels 4
 :html-extension "html"
 :body-only t ;; Only export section between <body> </body>
 :with-toc nil ;; don't export toc, it clobbers the YAML front matter
 )
("blog-static"
 :base-directory "~/Emacs/org/blog"
 :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|swf\\|gz\\|txt\\|el"
 :publishing-directory "~/WorkSpace/xiaoliuai.github.io/"
 :recursive t
 :publishing-function org-publish-attachment
 )
("blog":components ("blog-org" "blog-static"))

With this org-mode configuration, you have to create a folder _posts under the ~/Emacs/org/blog, then org-mode will export the folder and html files into the right place.

3.2 The head inserted into the org file for blog.

#+STARTUP: showall indent
#+STARTUP: hidestars
#+BEGIN_HTML
---
layout: default
title: Xiao Liu's First Blog
excerpt: First blog with org-mode, jekyll.
categories:
    - org
---
#+END_HTML

3.3 Comments

The two lines with comments form the main differences to ordinary html exportation. Jekyll will read the body of html files generated by org-mode and add it’s own heads to specify the styles. Org-mode will export the table of contents (TOC) at the beginning of exported html file, hence mask the YAML Front Matter. Disable the TOC can sovle this problem. However, there might be other solutions to change the position of TOC.

4 Build the server.

cd xiaoliuai.github.io
jekyll build
jekyll serve

5 Configuration

The simplest personalization of the blog site is editting _config.yml under the project directory. Following the attribute names in this file, you can easily understand how to specify the blog name, description, email address, etc.