Org mode as a writing platform

 · 2 min · torgeir

Emacs Hugo Org
  • Rescheduled from “[2023-05-10 Wed]” on [2023-05-12 Fri 20:37]

Doom Emacs’ module (org +hugo), found at modules/lang/org, makes it super easy to use org-mode as a writing platform with Hugo.

Here’s what you need to get started.

Create a file, e.g. blog.org and make sure to set hugo_base_dir to your hugo web site directory.

#+title: Blog
#+hugo_base_dir: ~/Desktop/hugo/

Create a heading that will correspond to your post.

* TODO Org mode as a writing platform               :hugo:emacs:org:
:PROPERTIES:
:EXPORT_FILE_NAME: org-mode-as-a-writing-platform
:END:

<content>

Enable (org-hugo-auto-export-mode) and save the file. You can do this with org local variables for the whole file to make it happen automatically.

Run the hugo server to see your new post on http://localhost:1313

hugo server -p 1313 --navigateToChanged

Now every change to your heading or the content below it will export to hugo automatically, and the web server will automatically navigate to and refresh your post’s content.

The best part about this is that all the normal org mode stuff you expect to work will just work, and translate to corresponding features in Hugo:

  • Headings marked with TODO become Hugo drafts. They are marked with draft = true in the Hugo front-matter. They will be navigated to for previewing what you write automatically when you save them, but are not visible in the web site archive. Add the --publishDrafts to the hugo server command to make them appear by default.

  • Headings that are scheduled, adding SCHEDULED: <2023-05-10 Mon> below them, will be marked with a corresponding publishDate = 2023-05-10T00:00:00+02:00 so they will not be published before the given date, even though they’re added to the source tree.

  • Headings that are completed, marked with DONE, will have the draft mark removed and appear as posts published on the given date.

  • Heading tags are translated to Hugo tags. E.g. will :hugo:emacs:org, as shown in the example above, translate to the hugo tags tags = ["emacs", "hugo", "org"] in the front matter.

Posts being plain org mode content, of course every org mode feature you use and love will work as you expect, for all your posts; searching headings, refiling content across files, looking up stuff by tag, heck even including posts you have queued or plan to write in the org agenda.

For me, that live in org-mode, this might actually lower the bar enough to make me keep posting tidbids of stuff I enjoy that I come across.

We’ll see how it goes.

References