I’ve recently updated my blogging setup so that I can write my posts using org-mode from within Emacs. Why? So I can get into the habit of using org-mode more frequently, and because I had a spare half hour to tinker with my emacs setup…

By default Hugo expects you to write your posts with markdown and it then converts them into static html for uploading to your website. Hugo does not (currently) support org mode files natively so I needed some way to convert my org-mode content into markdown. The two most obvious options are:

  • Use pandoc (which can convert from seemingly anything to anything)
  • Use org-mode’s publishing functionality to publish to markdown instead of html

As I am trying to get more familiar with org-mode, I decided to go for option 2.

My approach was to configure an org-mode publishing project that would make use of the markdown publishing functionality instead of the default html. I use the following config for that:

(setq org-publish-project-alist
         ;; Path to org files
         :base-directory "~/Documents/vurtcouk/org-content/"
         :base-extension "org"

         ;; Path to hugo project
         :publishing-directory "~/Documents/vurtcouk/content/"
         :recursive t
         :publishing-function gp-org-gfm-publish-to-md

It basically says, publish anything in the org-content folder to the content folder, as markdown.

Then I can publish with C-c C-e P x (I need to come up with a shorter key combo for that) and all my .org files in org-content will be converted to .md files in content.

One thing to note is that I’m using a custom publishing-function instead of the built in org-md-publish-to-md one. The reason for this is that hugo accepts github flavoured markdown, which provides better support for code blocks than vanilla markdown. In the org-mode contrib sources, there is an ox-gfm.el file that provides github flavoured markdown but it doesn’t provide a publish function. I merely created one based on the ox-md.el version:

(defun gp-org-gfm-publish-to-md (plist filename pub-dir)
  "Publish an org file to Github Flavoured Markdown.

FILENAME is the filename of the Org file to be published.  PLIST
is the property list for the given project.  PUB-DIR is the
publishing directory.

Return output file name."
  (org-publish-org-to 'gfm filename ".md" plist pub-dir))

The only other consideration is the front matter that hugo expects. I need to be able to make a section of the org file appear as-is in the published markdown file. To achieve this, I simply stick it at the start of my org file and wrap it in a #+BEGIN_EXPORT md and #+END_EXPORT. The EXPORT tells org mode to simply pass the content through unchanged when exporting/publishing.

And there you have it, a convoluted way of writing blog posts in org mode.