My Octopress Blogging Flow

After blogging with Octopress for a while, I have already gained some insights on it, and my publishing flow has been smoother. I think it is right time to share my flow as a reference.

The Flow

The following sections outlines the flow. The last section contains assorted tips and tricks. For the basic configuration of Octopress, please refer to the official website. I also recommend installing Alfred.app.

Creating a post: alfred workflow (blog publish)

Artem Yakimenko created an awesome alfred workflow for publishing and generating octopress websites. Use blog publish [title] to create a new post:

It then opens the post in your specified text editor with template.

Editing: Sublime Text.app + Marked.app + Marked App Menu (ST Plugin)

I use Sublime Text (ST) as my text editor, because it provides VIM keybinding and there is a huge repository of plugins. While editing, I use [Marked] to instantly render the markdown file and view the result. In fact, the title image shows my editing and previewing in action.

To make the process sweeter, there is a ST plugin called Marked App Menu that allows you to open the current file in Marked. Just search in ST Package Control to install it.

Previewing: pow + rake watch + pow alfred workflow

To preview the generate website, simply install pow and execute rake watch under octopress directory to monitor the change. Octopress official website provides some explanation. After installation, you can view your website locally at http://octopress.dev.

You should also install the pow alfred workflow, which can help you open pow website in a breeze.

Math Rendering: MathJax

Since I am an EECS student, I write a lot of Optimization, Machine Learning and Computer Vision stuff, which relies heavily on mathematics. Thus, writing math formulas is a must for me. MathJax is a javascript library for rendering math by writing LaTeX math. To do this, one needs to configure the site and link to the library. Put these two lines into <octopress>/source/_includes/custom/head.html:

<script type="text/javascript"
	src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

<script type="text/javascript" src="/javascripts/MathJaxLocal.js"></script>

The first script block loads MathJax, and the second loads a custom configuration in source/javascripts/MathJaxLocal.js. It is a good place to write your own macro there. For instance:

MathJax.Hub.Config({
	TeX: {
		equationNumbers: { autoNumber: "AMS" },
		TagSide: "left",
		Macros: {
			reals: ['\\mathbb{R}'],
			complex: ['\\mathbb{C}'],
			norm: ['\\left\\lVert#1\\right\\rVert', 1],
			given: ['\\:#1\\vert\\:', 1],
			data: ['\\mathcal{D}'],
		}
	}
});

MathJax.Ajax.loadComplete("/javascripts/MathJaxLocal.js");

Now you can write math!

\[e^{i \pi} + 1 = 0\]

There are a couple of good articles for reference:

1. Blogging With Math: Octopress, MathJax, and Pandoc
2. Writing Math Equations on Octopress
3. LaTeX Math in Octopress

Image hosting: Dropbox public folder

I host my images in Dropbox Public folder, since you can simply copy the public link and paste it to the post source, for example:

Image editing: Skitch + OmniGraffle

The previous image is done by a timed capture from skitch. For advanced vector graphics, I use OmniGraffle.

Markdown converter: pandoc

Pandoc is a swiss-army knife like tool that convert documents in multiple formats to several dozens of output formats. I mainly use it as the markdown converter for Octopress. A plugin can help you with that.

After installation, I update the markdown section of _config.yml with the following:

markdown: pandoc
pandoc:
  format: html5
  extensions:
    - smart
    - mathjax
    - bibliography: source/blog.bib
    - csl: _style/ieee.csl

which tells Octopress to use pandoc, and pass the option smart, mathjax and use the style file ieee.csl to format the biliography blog.bib. For example, refer to [@xiao2013optimally] generates refer to [@xiao2013optimally] (scroll down to see the [References] section).

Pandoc’s Markdown Reference: Dash.app and Dash alfred workflow

Dash.app is an API Documentation Browser and Code Snippet Manager. It provides an convinient alfred workflow that searches the documents:

opens

Tips and tricks

Continuously growing…

• There are lots of undocumented/less documented things in Octopress, which can help you write blog posts kinda ‘programmatically’. For example, https://www.ivanxiao.com returns the url of site, which is

https://www.ivanxiao.com in my case. In fact, anything in _config.yml is a variable under site.

Conclusion

In conclusion, Octopress is a revolutionary blogging framework. It provides a robust static site building framework (jekyll, bootstrap, scss, etc.) and allows complete control over the source, which is perfect for users that have basic coding and source control skills. In fact, it gives me a similar feeling of getting touch with a Mac. That is, compared to Windows, which is too close and does not provide built-in programming-friendly environment (Console, UNIX stuff, etc.), and compared to Linux, which is very open but too many variations and too many customizations needed, it combines their advantages by presenting a user- friendly interface and provides all sorts of underlying UNIX tools. I am very satisfied about this and my intention to write posts have revived. However, some sort of basic configuration is still needed. In particular, I would say Mathjax rendering and better image support definitely need to be integrated in the next release.

What’s your thought? Do you have any neat tricks publishing with Octopress? Please leave your comments.

References