Why ox-hugo?

    A picture is worth a thousand words.

So let me show you this screenshot that took on my phone (running Emacs in Termux app on Android), showing the single Org file that serves as a source of this whole documentation site.

/images/ox-hugo-doc-source-viewing-in-Termux-Android.png

Using Org just as a markup like Markdown is a miniscule part of its complete feature-set. Org also allows stuff like:

  • Easy ordering/manipulation/commenting of subtrees
  • Creating tables (with even formulas like in Excel)
  • Directly including source code snippets from external files (instead of having to copy/paste them in)
  • Running code snippets within the Org file and embedding the results (Org Babel)
  • ..

Using Org for content writing allows using built-in Org features to translate to Hugo front-matter:

  • Org uses an outline structure and can inherit meta data (tags and properties) from one subtree to children subtrees.

  • Using that feature, one can tag one tree as emacs, and everything under that tree (all posts under that) will get that tag automatically.

  • The same concept applies to inheriting any Org property meta data like menu entry, category, section name, etc.

  • A subtree can be quickly marked to be in TODO state (default binding C-c C-t). A TODO post is marked as a draft Hugo post.

  • The menu-item weights, page weights and taxonomy weights can be set to be auto-calculated so that the menu items or post order in the final HTML appear in the same order as the respective subtrees in Org.

    If the subtrees are re-ordered in Org, the weights get changed too.

  • One can have a subtree with section property set to “posts” and all post subtrees under that will go to that section. Similarly another parent subtree can have that property set to “articles”, and so on.

  • Images can be displayed inline in the Org buffer.

  • After save hooks can be set up in Emacs so that each time I save the file, only the current subtree in Org gets exported to Markdown. With the Hugo server running with the --navigateToChanged switch (this allows auto-changing the preview to the last changed post), the flow is seamless – Save the Org file and see the exact changed post in browser.

  • All posts can simply be subtrees in a single Org file. That way one can take advantage of Org subtree filtering and searching functions (org-sparse-tree bound to C-c / by default).

  • (and much more..)

Fork me on GitHub