Setting up a blog with org-mode

Table of Contents

org-mode is an incredibly powerful system, with its primary function being authoring documents. However, if you ask any Emacs user, it’s a lot more than just a markdown. You can manage agendas, write literate programs, even make presentations!

In this post I’ll be describing how to generate your own blog system using Emacs and org-mode.

Exporting org mode

org-mode has several exporting functionalities i.e. the ability to generate different formats for a single file. These formats include (but are not limited to):

  • ASCII
  • Latex (with auto PDF compilation)
  • Markdown
  • ODT
  • HTML

That last one is of importance; we can generate HTML 5 documents, viewable in your browser, of your org mode buffers!

In fact, you can stop right now and generate your own blog system using this alone: for each blog post generate a corresponding HTML file, then host those files on a server.

Publishing

The org-mode authors, of course, accounted for this idea, so there is an inbuilt feature called publishing. It essentially allows you to describe a system of org mode files and how they should be output.

org-mode-publish-project-alist is the variable that defines a publish project. It’s a set of lists where for each list the first item represents the name of the project and the remaining items describe how the project publishes files.

The main properties are pretty self documenting:

  • :base-directory: where are the org files contained?
  • :publishing-directory: where should the output files be stored?
  • :publishing-function: what format do we want to output?

After this point its a process of inspecting the publishing-function of choice for variables you may want to substitute, as the rest of the properties are specific. Some common publishing functions are:

  • org-md-publish-to-md
  • org-html-publish-to-html
  • org-reveal-publish-to-reveal
  • org-latex-publish-to-latex
  • org-ascii-publish-to-ascii

You can change a surprising amount of details in the output file just from tweaking parameters.

Basic workflow

Using org-publish-project you can publish any configured projects. It even tracks if a file has been modified (like Make) so it’ll only compile what’s necessary. I usually compose this with an scp call to host the output articles.

Hugo

Hugo is a static site builder written in go. It’s really fast, with a good template system and, in my opinion, clear system for layout and partials. It provides a lot of nice features ‘for free’ (in the sense that your output files will be just plain HTML). It uses markdown files for posts, compiling them into HTML files.

ox-hugo is a project which allows org files to be output into Hugo-like markdown files. By using org-publish with ox-hugo, you can create an automated system for generating Hugo markdown.

Though this is adding a step in the process, which is independent of Emacs, the features that Hugo provides far outweighs this.

You will have to write your own publishing function for org-hugo* as it doesn’t come with one, but it’s very easy to write one (just look at org-html-publish-to-html):

(defun org-hugo-publish-project (plist filename publish-dir)
  (org-publish-org-to 'hugo filename
                      ".md"
                      plist
                      publish-dir))

The hugo command line interface also provides a ton of extra features, in particular a development server.

Complete workflow

From here on out, this will be specific to my website, so keep that in mind.

My website’s root is written purely in HTML, and I don’t want to subsume it into Hugo itself. This makes hugo server kinda useless as Hugo assumes your entire website is going to be written in it (which means referencing assets relative to the Hugo folder, for example).

To get around this, while still having some semblance of hugo server’s hot reloading, I use two tools in my local environment: python -m http.server and nodemon. I run the HTTP server in my website folder root and use nodemon to watch for file changes in the blog sub folder (using hugo to recompile when this occurs).

In Emacs I use (compile) to run this server while writing my blog posts. In fact I’m doing that right now, and it provides a good workflow.

In terms of sending articles, it’s the same scp deal.

Conclusion

An integrated system that leverages my favourite editor (Emacs), my favourite text system (org-mode) while being surprisingly easy to setup. Triple win!