Creating and Maintaining a Blog

Table of Contents

1 动机

俗话说,好记性不如烂笔头.我从高中时代开始记笔记,一直到硕士毕业.这个好习 惯给我带了巨大的好处.然而,纸质的笔记难以管理和携带,尤其是对我这种一年 至少搬一次家的留学狗来说.再加上硕士毕业后,老板给配了一台Macbook Pro,就 逐渐地抛弃纸质笔记.可是由于自己的惰性,和电脑上查询资料的便利,逐渐丢失 了记笔记的好习惯,博士毕业后看着自己的水论文,才悔之晚矣.

电脑上记笔记有N种办法,相应的软件也是多如牛毛.著名的evernote就是其中翘 楚.但是使用之后觉得,evernote适宜当便条本来记录一些零碎的东西以及利用 webclipper来抓网页以便之后阅读.正儿八经的写笔记,作总结,对我来说总感觉 哪里有点不对(我确定自己不是处女座).最后作为一个有(zhuang)范(bi)的程序 员,果断走上了 emacs + org-mode 的道路.可是光靠org-mode还难以治疗我那经 过4年滋生壮大的懒筋.于是乎我再(ji)进(xu)一(zhe)步(teng),准备开始写博客.其 实作为一个程序员,这个时候才开始写博客实在是有点太懒,太晚.但是我觉得自 己还能抢救一下,于是趁这几天有空,开始搜帖子用org-mode配合 jekyllGitHub Pages 来搭建看起来高大上的个人博客.

2 Initialize the first blog   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.

2.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.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
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.
-- _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.

2.3 From org-mode to jekyll

2.3.1 Configuration of emacs org setting

 :base-directory "~/Emacs/org/blog"
 :base-extension "org"
 :publishing-directory "~/WorkSpace/"
 :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
 :base-directory "~/Emacs/org/blog"
 :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|swf\\|gz\\|txt\\|el"
 :publishing-directory "~/WorkSpace/"
 :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.

2.3.2 The head inserted into the org file for blog.

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


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.

2.4 Build the server.

jekyll build
jekyll serve

2.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.

3 Writing Blog Using Org-mode and Octopress   blog

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.

3.1 Octopress Installation

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

3.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:// .rbenv
git clone 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

3.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/ 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. Copy octopress repository

(_I suggest to clone shallow copy with option_ depth)

git clone git:// octopress
cd octopress Install dependencies
gem install bundler
rbenv rehash    # If you use rbenv, rehash to be able to run the bundle command
bundle install Install the default theme

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

rake install

3.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.3 Emacs Configurations

3.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)
;; to
(org-map-entries (lambda () (org-show-subtree) (org-jekyll-export-entry project))

3.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.3 Conflict and Test

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

  • 下划线
  • 表格竖边框

3.3.4 TODO [1/4]

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

4 博客美化,定制

我的博客美化定制基本上照抄Octopress折腾之路(2)Octopress折腾之路 (4),还没抄完,汗. Mac上面的octopress对于原版的tag插件兼容不太 好,这篇博文里提到可以使用tag插件的Issues里面给出的解决方案:修改 plugins/tag_clound.rg 文件.在我所使用的版本中,需要修改的文件是 plugins/tag_list.el.

4.1 Install the 3rd-party theme (optional)

4.2 Add 3rd-party tools (optional)

4.3 添加评论

  • 注册一个Disqus账号,在菜单里找到admin,add to site. 生成评论之后会得到 一个博客码.
  • _config.yml 里面找到 disqus_short_name:, 把刚才得到的博客码写 进去.然后在emacs端的propoties里面加上 :comments: true,总之就是要使 得导出的html片段的头部有 comments: true 的标记.然后就OK了.

4.4 TODO [0/2]

  • [ ] 给代码块加行号
  • [ ] 进一步美化(抄完)

Date: 2014-10-29

Author: Xiao LIU

Created: 2015-02-28 Sat 22:37

Emacs 24.4.1 (Org mode 8.2.10)