Deploying Hugo Drafts, simplified

Sun, 31 May 2020 17:19:00 +0530

This is a follow-up post to my last post, Deploying Hugo Drafts. Kaushal Modi, the author of ox-hugo (a tool that lets you compose in org-mode and use Hugo to export), let me know about the build options in Hugo.

Have you looked at the new _build options: https://t.co/Nj8Uefis6Q. I haven't used them yet, but looks like they fit your use case.
— Kaushal (@kaushalmodi) May 30, 2020

The build options in Hugo let you configure building a post for different use cases like render a post but hide it in lists, or don’t render separate pages for posts and only show them in lists, etc.

To use these build options for my use case – being able to share draft post links with friends, without them appearing in the index page or RSS feed – I just need to add the following to my draft blog posts!

_build:
  render: true
  list: false

But, how do I do this with ox-hugo? I know ox-hugo doesn’t yet have this feature, for sure, because Kaushal mentioned that he hasn’t tried it out yet.

I checked to see if I could use the EXPORT_HUGO_CUSTOM_FRONT_MATTER property to get it to generate this extra metadata for each blog post. But that didn’t work. The property assumes all the arguments to it are top level front matter keys and values, which is good enough for “normal” use cases.

EDIT [2020-05-31 Sun]: I previously manually created the drafts directory with the _index.md, but Kaushal pointed me to more docs, again! :) There’s also an issue for adding an easier way to add these build options from ox-hugo.

I created a subtree like this in my org file, that creates the drafts/_index.md file with the required front matter and build options.

* Drafts
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_SECTION: drafts
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: yaml
:END:

#+begin_src yaml :front_matter_extra t
  _build:
    render: false
    publishResources: false
    list: false
  cascade:
    _build:
      render: true
#+end_src

The build options for the index page turn off publishing and showing it in lists. With the cascade option, we can get the options to all the children – any files created in the drafts directory, but also override the render option to be true. In other words, the configuration above would translate to adding the following to every draft post:

title: A How-to on Hugo Drafts
_build:
  render: true
  publishResources: false
  list: false

Now, I just need to make sure that all my draft posts are created in this drafts directory. ox-hugo allows doing this by simply using the EXPORT_HUGO_SECTION property on my post subtree. I added this additional property to my helper function that I use to create hugo blog posts from any subtree.

* DRAFT A How-to on Hugo Drafts :blogging:hack:
:PROPERTIES:
:EXPORT_FILE_NAME: how-to-hugo-drafts
:EXPORT_HUGO_SECTION: drafts
:EXPORT_DATE: [2020-05-31 Sun 16:51]
:END:

I’m now all set to publish draft posts without requiring to use rsync and two hugo builds. :) Publishing a draft post would need me to remove the DRAFT todo keyword, like before, but additionally also remove the :EXPORT_HUGO_SECTION: property on the subtree. This should be quite quick to do, or pretty easy to put into an interactive function if required.

Deploying Hugo Drafts

Sat, 30 May 2020 19:07:00 +0530

Update [2020-05-31 Sun 17:23]: I published a simpler workflow for this, using Hugo’s build options that I wasn’t aware of, because they are relatively new.

A few friends and I run a weekly writing club similar to this. Once we have our drafts ready, we usually share them for reviews, etc.

Previously, I used to use Nikola, and it’s default behaviour is what worked well for this workflow – share the posts URL with reviewers, but the post shouldn’t appear in the feed, post list, etc.

If you set the status metadata field of a post to draft, it will not be shown in indexes and feeds. It will be compiled, and if you deploy it it will be made available, so use with care. If you wish your drafts to be not available in your deployed site, you can set DEPLOY_DRAFTS = False in your configuration.

I moved to using Hugo a few years ago. By default, it doesn’t publish the draft posts, but you could ask it to do so using the --buildDrafts option. But, that doesn’t do what I want – draft posts are treated just like any other post, and they appear in the feeds, post list, etc.

Given how fast hugo builds are, though, it is pretty easy to hack-up the behaviour I want.

Run a build with drafts, say to dev directory.

DEV_DIR="dev"
# Build drafts to dev dir
hugo --cleanDestinationDir -D -d "${DEV_DIR}" > /dev/null

Run a build without drafts, to public directory.

PUBLIC_DIR="public"
hugo --cleanDestinationDir -d "${PUBLIC_DIR}"

Copy the drafts from the dev build to the public build

rsync -ri --ignore-existing "${DEV_DIR}"/ "${PUBLIC_DIR}"

Deploy the public build

The code above is here as a single script. Here is the full deployment script for my blog.

Blogging on Noetic Nought

Deploying Hugo Drafts, simplified

Deploying Hugo Drafts