Nonsense

some of it isn't, but opinions differ as to which is which

Hugo: A Different Twitter Shortcode

Hugo has a handy little shortcode to embed tweets into a page. It takes the form1:

{{ < tweet [ tweet id ] >}}

So for example, in a Markdown page:

{{ < tweet 763188308662898691 >}}

Produces this:

Under the hood, it’s using the Twitter API to provide the embed code via GET statuses/oembed. Which is fine and all, but there are times when you don’t want the default embed style, and want to use some of the options the Twitter API provides. In a project, I wanted to hide previous-tweet-in-a-thread that Twitter provides by default, using the hide_thread option. (If I want to display threading, I can do it myself with hardcoding and CSS, using styling that’s a bit easier to follow.) The easiest way to turn off the default Twitter thread display was to make my own shortcode that I could call instead of Hugo’s internal one2.

In layouts/shortcodes, I have tweet-single.html, which looks like this:

<div>

  {{ (getJSON "https://api.twitter.com/1/statuses/oembed.json?dnt=1&hide_thread=1&id=" (index .Params 0)).html | safeHTML }}

</div>

And now I can call tweet-single just like I can call tweet:

{{ < tweet-single [tweet id x] >}}

I, uh, also told Twitter to turn off tracking for that embed via dnt, because I’m a decent and not at all paranoid person.

Now that everything is exactly the way I want it, I should probably upgrade Hugo and see what needs to be fixed.


  1. I’ve added extra spaces to the start of the shortcode in these examples to keep Hugo from trying to run them as actual shortcode calls. You’ll need to remove the space between "{{" and "<". [return]
  2. All of this works until Twitter changes the api, or Hugo changes under my feet, obviously. [return]

Hugo: Section Sorted by Taxonomy

One of the other weird-ish things I needed to be able to do for this site setup was the Projects page over there to the side. It’s the section page for the Project section, and on it I wanted to sort all my project posts, and only my project posts, by some sort of assigned type, rather than listing by date or whatever.

I’m doing this the cheaty way by just using the ‘tags’ taxonomy for blog posts, and using the ‘categories’ taxonomy only for project posts. I didn’t just want to link to the taxonomy list page, because then I would have to fiddle with the page name and title and whatnot to make it what I wanted. This meant that I needed to pull the full “category” taxonomy listing into the “project” section list template.

In the /layouts/project/project.html template file I have this in the main content <div>:

<section> 
    {{ range $key, $value := $.Site.Taxonomies.categories }}
    <h2> {{ humanize $key }} </h2>
        <ul>
        {{ range $value.Pages }}
            {{ .Render "li" }}
        {{ end }}
        </ul>
    {{ end }} 
</section>

It took surprisingly long for me to find a bit of sample code to modify for this, so here’s hoping I’ve provided another potential search result for someone trying to figure this out. The ‘humanize’ bit in there is because I am difficult and I like capitalization in my organizational structure.

This is using Hugo version 0.37.1 at the time of writing.

Hugo and Footnotes

Hugo does Markdown footnotes! Excellent. However, Hugo tends to assume you will never have more than one post with footnotes visible on a page, because Pretty Links.1 Awkward if you like multiple full posts on the homepage and you’re inordinately fond of footnotes like me. This is easily fixable! I had to spend some time figuring out how, so I’m putting the details here. (Current as of Hugo version 0.37.)

Footnote reference link styles are part of the Blackfriday Markdown engine internal to Hugo. They get adjusted in a separate blackfriday section in your site config file, using the plainIDAnchors setting. To turn off plain ID anchors, and have footnote reference links that reference the post ID as well as the footnote number, this needs to be in config.toml (in the root of your Hugo site directory):

[blackfriday] 
plainIDAnchors = false

If you’re using config.yaml, it’ll be:

blackfriday:
    plainIDAnchors: false

And then you should be able to put all the footnotes you want wherever you want.


  1. In other words, the default Hugo settings assume you’ll prefer short reference links that point to ‘fn:1’ rather than longer, more defined links that point to ‘fn:[long unique ID]:1’ [return]

Some Thoughts About Hugo

Let’s get one thing straight off the top. I really like Hugo, it’s quite fun conceptually, copying things from Scrivener into a Markdown file is not terrible, and should get quite a bit easier/automatic once I can get my hands on version 3 and get things set up properly. Now that I’ve just about got my site’s template files set up properly, that’s all that I really need to do.1 Hugo lets me fiddle with basically everything, and set most things up the way I want them. I think it was also probably the easiest way for me to make this type of website. I’m planning on using it for the foreseeable future.

However.

This whole, fairly uncomplicated site was notably more difficult to set up than I anticipated. I have a development background,2 and that helped quite a lot, and my prickly stubbornness got me the rest of the way.3 There are a few reasons for why this was difficult.

First, I’m playing with version 0.39 (currently) of an open source tool. This probably means you should take most of my following complaints with a grain of salt, although you should also remember that I’m claiming that this was the easiest tool to use that would do what I needed. That says things about my available options. The nice thing about Hugo is that you can get it as a standalone executable. I didn’t have to install a package management system, or manage dependencies, or install an entire language interpreter. I did have to install git (a command-line version control system) to make installing themes easy. I did have to deal with documentation that was pretty inadequate at times.

I left development over five years ago, so practices and tools and workflows have changed, and also now I get pretty grumpy when software assumes I’ll be some sort of developer when I use it. Hugo definitely does that. It’s really powerful, but a lot of its power comes because any theme’s template files are written in a combo of HTML and Go inclusions, with maybe some Javascript if the theme developer was feeling ambitious, and while a lot of settings could be abstracted out from the theme files to the site configuration file, they generally… aren’t. Hugo also doesn’t come with anything useful in the way of a default theme, so you end up needing to get one from the theme site, just about all of which are community provided. I think? It’s not very clear.

Which is fine, but an individual theme isn’t guaranteed to be up to date with your new version of Hugo, and you’ll probably end up wanting to change things a bit, and maybe the template files weren’t quite complete in the first place, and the next thing you know, you have a bunch of empty pages that should be holding Stuff.

Again, this is the static site generator that had the easiest entrance requirements on a Windows machine.

So I really enjoy what I can do with Hugo, and again, I intend to keep using it, but I’m not sure I’d be able to recommend it to that many people who want to set up their own site. The learning curve is waaaay steeper than the blogposts by adoring developers who used it to put up some project notes and a two-post blog about their Hugo Experience would have you believe. This is extra true for people running things on a Windows desktop.

A lot of this could be fixed with a really solid useful template that tries to abstract out a bunch of settings to the site configuration file so users don’t have to dig into the template files until they were ready, and that is also kept up-to-date. Which may already exist! But I was having a lot of trouble trying to find it. A lot of problems could also be fixed with clearer documentation for Hugo itself, particularly by describing how to put all the various templates and functions and variables together into a cohesive whole. It’s really very by-developers-for-developers currently, and I don’t think it has to be. There’s nothing about constructing a static website that demands that only professional software developers be able do it, and I’d really like to see some more widely usable options here that don’t rely on software-as-a-service or drag-and-drop hand-holding.


  1. Well, I also need to get a script or whatever sorted to SFTP the constructed site onto my webserver, but that should be pretty minor. [return]
  2. C++ embedded, nothing even remotely frontend, but I can look at unfamiliar code and not run screaming. More importantly, I know when to expect there to be code. [return]
  3. Ask my husband how often I turned down his offers to help because “I need to learn how to make this work myself, dammit.” Apparently I felt very strongly about how it was an Important Life Skill. [return]

Help, I Want My Software Back

I’m trying to fit my head around the absurdly sudden realization that tech and software and the internet mostly don’t exist for me anymore. They exist for developers, and they exist for people that use a lot of Facebook/Google/Twitter/Apple, but they don’t exist for me, user with a Windows desktop machine and a willingness to fiddle with settings and install bits of software to do individual things, but not to install five package managers and three development environments just to get a tool running; an entire market sector seems weirdly gone, and I don’t know what to do with this discovery.

I’m probably hitting middle age a wee bit early. Is this how people feel before they have that mid-life crisis? Like everything they used to know is gone now, and nothing that remains quite makes sense?

You get apps, or you get cloud services, or you get IoT devices, or you get tools made by developers for developers. There is very little else. Why? I can see how we got to this place, via App Stores, and walled gardens, and Silicon Valley-style venture capitalism. Either you want everyone as your end-user/product, thus narrowing your design and UX choices, and your capabilities, or you want to be able to assume that the end-user will just make their own crap or cobble together a twelve-step workflow if they can’t get yours to work properly. Was this inevitable? Is this the way things should be? Why isn’t there any middle ground? Why do I keep feeling the need to yell at these kids to get off my lawn?

There are 4-5 standalone RSS readers for Windows. Maybe one or two are being currently updated, the rest have had their development abandoned. The ones that exist don’t really do what I want them to, or are annoying to use. I can sign up for an online RSS aggregator, or install my own on a server, or use a browser plugin so I will have to figure this out all over again the next time I switch browsers. None of these things are exactly what I want. It’s so weird to not be able to find exactly what I want. I need to think about my wants and needs again.

I’m starting to think I may be old and crotchety.

I set out to make this static website, and the only tools I could find for this were developer-oriented. Hugo was the only one that didn’t require me to install a full-on development environment, although I still needed to install git (a version control system) to easily download themes for it. Dreamweaver still exists, but it’s an Adobe Creative Cloud subscription app now. You can only buy the very basic set of Microsoft Office applications as a one-time purchase. Everything else is subscription-based. All of this was coming, I heard people yelling about it ten or more years ago, but it didn’t seem to apply to me then, and I didn’t think it would really turn out this way. The height of hubris, really, for me to assume that software and the internet would continue to exist in ways that I enjoyed and found useful while I waltzed off to poke around in the shiny new ecosystems that were springing up.

Now, as I want to pull back into more individualized options from the larger internet ecosystems that have taken over so much, as I want to feel like I own my own systems of working again, those options are disappearing. Or have been disappearing for the last decade. I feel like I should be in mourning, but I’ve still not really convinced myself that that’s reasonable or sane.

At least PC games have never really gone away. Escapism is vital.