Table of Contents
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.
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
jekyll new xiaoliuai.github.io cd xiaoliuai.github.io jekyll serve
Then you can see the portal page by opening
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,
_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
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
~/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
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
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.