humans.txt

I just added a humans.txt file to this site.

I learned about this idea a few weeks back and really liked it! It’s simple, it’s plaintext, and it spits in the face of the subtext of robots.txt being “the internet is for robots (and not for humans).”

You can read more about it here.

Implementation Details

Initially, I tried to “just” make a Page at the top-level of my content (similar to how my about page) is generated, but have hugo produce a text file instead of HTML.

Once I got the output format hooked up¹, I was off to the races … except … it looked (literally) like this:

Last update: {{ now.UTC.Format "2006/02/01 15:04:05 MST" }}

Shoot, I thought, can I only have template directives render when outputting HTML files? I really wanted this line in particular to render so I didn’t have to remember to update the date every time I pushed changes.

Many, many hours of random googling and “what about this random configuration tweak?” later, I realized that if I put all the templating in the layout file instead of directly in the content file, then it would work.

In fact, as I began writing this post, I attempted (and failed) to use a {{ ref }} directive. It occurs to me that template directives may only be possible in layout files, full stop, and that it’s simply been so long since I’ve done much writing here that I’ve forgotten, if I ever knew that to begin with.

Weird and Gross™

Now, because I moved some of the rendering from the content to the layout, I was now in a situation where my layout needed to render, in rough pseudocode:

{{ render stuff-before-LastUpdated-in-content-file }}
Last update: {{ now.UTC.Format "2006/02/01 15:04:05 MST" }}
{{ render stuff-after-LastUpdated-in-content-file }}

which is … Weird and Gross™.

Data Files

My next idea, then, was to move all of the humans.txt metadata into frontmatter, and create a dedicated page type that whose layout would render entirely from frontmatter. That looks like this, and it totally works!

The downside here is my content file is now (in theory) an ever-growing frontmatter document with no actual content in it. Which is Weird and Gross™, but in a different way.

Then I stumbled onto data files, which

are not for generating standalone pages. They should supplement content files by … extending the content when the front matter fields grow out of control

Well, well, well! If that isn’t exactly the problem I’m trying to solve!

So, now my layouts/humans/single.txt renders data from three files:

Much nicer!