Overview

This is the simplest but smart self-publishing workflow.

org-mode -> ox_hugo -> hugo -> static html -> git commit -a -> git push -> github pages

Everything is according to the universal principles of being almost “pure functional transformations” of a structured and decorated text, together with version control, which provides sort of immutability (of the previous versions).

At each stage or step we delegate some aspect to an appropriate external vendored tool.

We start with the most general and versatile format - org-mode and then gradually specialize it (via markdown being exported into a static html by hugo) to be published on the Github Pages.

Using org-mode as the structural text is the key. The same .org file could be exported into almost everything, including LaTeX, and then a good quality .pdf.

The standalone pandoc tool can be used separately with the source .org files.

The principles

We are trying to separate the concerns and to decouple everything (at each step).

  • Each format is reproducible (from an org file) and gets preserved.
  • Each tool does its own thing only, and, hopefully, does it well.

The tools

  • We use Emacs, which formats the code, checks spelling and grammar, etc.
  • We write everything in org-mode files, decorated with the Hugo-specific properties.
  • ox-hugo generates all the markdown files inside of $HUGO_BASE_DIR/content.
  • it follows simple directory-based layout, so we just have a nested directories.
  • it runs the hugo binary which generates the static site html according to the theme.
  • we use git to version the resulting html content and to push it into github.

The properties

We just specify default properties which Hugo requires (at least the section).

  • HUGO_SECTION (required by Hugo)
  • EXPORT_FILE_NAME to use a whole sub-tree (a directory) for a single “post”.
  • HUGO_BUNDLE