Writing Blog Using Org-mode and Octopress

After the installation and the configuration of jekyll along with the org-mode. I tried to find some configurations to facilitate the creation of org files (create file with date in front of file name, insert heads, etc.) I did not realize the existence of relative emacs packages in elpa and asked google for solutions. My inefficient search key-words let the google returns undesired answer: the octopress. Octopress is based on the jekyll, but provide richer blog settings. Finally, I migrated to octopress and use it to manager my github pages.

1 Octopress Installation

Installation of octopress is little complex since it requires low version ruby.

1.1 Installation of old version ruby with rbenv

You can following the instructions on the official manual. 

cd # go to home
git clone git://github.com/sstephenson/rbenv.git .rbenv
git clone git://github.com/sstephenson/ruby-build.git .rbenv/plugins/ruby-build

Add two lines into the end of shell profile (.zshrc in my case). 

export PATH=$HOME/.rbenv/bin:$PATH
eval "$(rbenv init -)"

Then reload the profile by source ~/.zshrc or resume the terminal. The installation of rbenv and ruby-build can be replaced by 

brew update
brew install rbenv
brew install ruby-build

Attention: the shell profile must be modified with both installation methods.

Then install ruby 1.9.3, which is required by octopress. 

rbenv install 1.9.3-p0
rbenv local 1.9.3-p0
rbenv rehash

1.2 Setup the octopress

My setup experience is basically the same with the official manual. However, after the installation, I replaced the octopress directory to ~/WorkSpace/xiaoliuai.github.io because it actually becomes the repository of my github pages (magnificent!). So I suggest to clone the octopress git repository into the directory with the same name of the repository of your github pages at the beginning.

1.2.1 Copy octopress repository

(_I suggest to clone shallow copy with option_ depth) 

git clone git://github.com/imathis/octopress.git octopress
cd octopress

1.2.2 Install dependencies

gem install bundler
rbenv rehash    # If you use rbenv, rehash to be able to run the bundle command
bundle install

1.2.3 Install the default theme

(_I suggest to ignore this step and install the 3rd-party theme directly_) 

rake install

2 Common usage

  • Local site

    The octopress puts the generated web site, including the pages, layouts, images, etc. into the public folder for local preview. The source folder contains all the source files used to generate the site, including the layout HTML files, Java-scripts, style-sheets, etc. It can be seemed as a hyper _posts folder that contains source files more than blog HTML files. The familiar _posts folder used in jekyll is under this folder. Let’s start blogging.

    First, go into the octopress folder, type rake new_post["title"], octopress will ask you to give a blog tile, then creates a markdown file into the _posts folder with jekyll format (concatenate date and the title as the file name). 

    rake new_post["My first blog"]
# create source/_posts/2014-10-28-my-first-blog.markdown

    This file should be edited respect to the jekyll protocol.

    Second, ran rake generate to generate the site in public and then ran rake preview to mount a web-server at http://localhost:4000.

  • Deploying to Github Pages

    Octopress integrated commands to let you deploy the generated site to the github. 

    rake setup_github_pages

    This command will ask you for a URL of the Github repo, then it will store your Github pages repository URL as the origin remote and change the octopress remote to octopress. The directory of octopress becomes the repository of the source branch of the origin remote (your Github Pages repo). The _deploy directory, becomes the master branch of the origin remote. Run command: 

    rake deploy

    will update the files in public to _deploy, then push the changes to the master branch of the origin remote. To keep your settings and sources tracked, run 

    git add .
git commit -m'Your message'
git push origin source

    to push the contents in octopress directory to the source branch of the origin remote.

    One thing confusing is that one repository (master branch) is under another repository. But the directory _deploy is in the gitignore of source branch, hence solve the self-contain problem.

3 Emacs Configurations

3.1 Lisp package org-jekyll

There are lisp packages in melpa that provide smart org-jekyll edit functions.The great advantage of this package is that it generates blogs with respect to the entries with blog tag. In detail, it generates HTML files with proper time stamp before the file names. Therefore you don’t have to take care about the file names (you have to manage the org file name if you use other tools). Note you have to specify the time stamp in property of entry. This package does only export the section names, modify the elisp script following the issue to export the contents. Use org-jekyll-export-blog to export the blog HTML files. 

;; change
(org-map-entries (lambda () (org-jekyll-export-entry project)
                               "blog|BLOG"))))
;; to
(org-map-entries (lambda () (org-show-subtree) (org-jekyll-export-entry project))
                               "blog|BLOG"))))

3.2 Org-octopress package

The package can be installed from elpa, but it does not support the tags. Hence, I modified the ox-jekyll.el file, duplicated all the variables and expressions contain categories and then replace them by tags. After reopening emacs, it successfully exports the tags into HTML files under _posts.

3.3 Conflict and Test

标准的org-mode模式在导出为jekyll的HTML片段的时候,有一些导出格式需要 相应的css或者header支持. 不兼容列表

  • 下划线
  • 表格竖边框

3.4 TODO [1/4]

  • [X] tags
  • [ ] functions of contents in setupfile.org
  • [ ] org-octopress generate publish folder.
  • [ ] In org-jekyll, YAML markup is mentioned many times. I have to study into it when I have time.