A guide to navigating the non-obvious nature of the process for providing the data my plugins want … and that you want to give them.
Option One: When You Want to Copy/Paste and Keep Your Fingers Crossed
This option uses the Micro.blog plugin parameter interface. The parameter interface is great when all we need to store is a simple string or number value. When we’re looking to feed data that a plugin can convert into a map/table/dictionary/pick-your-programmatical-term-of-choice-for-storing-key-value-pairs, however, we’re kind of purposefully breaking the interface.
How, you ask? Well, if you paste in your totally valid JSON object, click Update Settings, move on with your life, suddenly recall you meant to enter a particular value into the field for one of the plugin’s other parameters (say some simple parameter like
Twitter Username), click again on Update Settings … so … if you do that, guess what … you just totally boinked the JSON object parameter. It didn’t get loaded back into the field the same way you had pasted it in there the first time and now you have to go find (or recreate) the data to copy/paste once more.
Anyway, if this sounds fun. You already know what to do; but, let’s break this down for the f$&k of it.
⑴ Hit up the Plugins tab and locate the plugin you wanna feed data to (we’ll be feeding data to plugin-cards for the purposes of this post).
⑵ Click * ⚙︎ Settings* to the right of the plugin’s name.
⑶ Enter any parameter values and/or data you want to configure and click Update Settings.
Here’s what I pasted into that
Card Data (JSON) field (if you’re new to JSON, this is a totally valid JSON object):
Boom! A brand new
config.json file was just created in the plugin’s directory. Wanna see it? Here’s how to navigate: Design → Edit Custom Themes → Select Plugin.
Let’s look at what got stored. Here’s the prettified version of
Check out all those escaped quotation marks. What we are feeding the plugin as
card_twitter_usernameis the string
"moondeerdotblog". Cool. That’s what the plugin wants. We are also feeding the plugin a string for
card_data. Now the plugin has to try unmarshaling that string into a map (which is what Hugo circles when presented map/table/dictionary/pick-your-programmatical-term-of-choice-for-storing-key-value-pairs). Something gets messed up in translation … Hugo will throw a fit and refuse to build your site. We can do better.
Option Two: When You’re Ready To Tinker
So I’ve already mentioned, under option one, how to navigate to a plugin’s templates and look at what all was installed.
⑴ Go to the Design tab and hit that Edit Custom Themes button.
⑵ Find the plugin in the list of plugins and themes
⑶ Gaze in wonder at the contents of the plugin’s directory.
Guess what. As soon as you chose to install that plugin, you gained god-like power over the contents of its files. You can edit them. You can delete them. You can even add to them. This is what you are about to do. Totally safe. Totally harmless. You are just gonna manifest some chunk of zeros and ones into existence and give ‘em a place to stay.
⑷ Hit that New Template button.
Looks like we got two fields we need to fill in before we hit Update Template.
Sticking with the plugin-cards example, we are definitely going to create a file whose location begins all
data/plugin_cards/data. How the location ends will depend upon how we feel like storing our data. We are no longer confined to the use of JSON. JSON would be totally valid. Our file content would be identical to the chunk of JSON code I plopped up there and identifed as a totally valid JSON object. If we did so, the file location would end with the
.json extension, like so:
But, Hugo is just as happy with YAML as it is with JSON. You could toss the JSON into this converter and store it as a YAML file. It would look like this:
If we did so, the file location would end with the
.yaml extension, like so:
Last, but not least, we have my new favorite markup language for Hugo data … TOML.
As it is with YAML, so it is with TOML. Stick that JSON into this converter and you get:
For the purpose interacting with Hugo, I have come to prefer TOML, so most of my documentation will be using TOML to persist data and configure sh$t. If we choose to store our data as TOML we would use the
toml extension, kinda like:
⑸ With the path to our new file determined and its contents inserted, it is time to hit Update Template.
⑹ Rejoice in never needing to revisit the plugin parameters interface. If, however, you think it would be cool to not have to repeat this process every time you want to update the plugin … check out option three (which is the method I use for feeding data to my plugins from my custom theme).
Option Three: When You Value Persistence
The steps for option three are nearly identical. The difference lies in the directory within which we will create the data file. What we need is a custom theme. If you have one already, go ahead and skip down to the file naming conventions I have adopted. If you do not already have a custom theme, buckle up, here comes some super-easy sh$te you’ll be embarassed about having been intimidated by.
Creating Your First Custom Theme
⑴ Hit the Design tab.
⑵ Hit Edit Custom Themes.
⑶ Hit New Theme, give your theme a name, and hit Add Theme.
⑷ Head back to the Design tab, select your new theme from the Custom Theme drop-down, and hit Update Microblog Settings.
⑸ Hit Edit Custom Themes and find your new theme in the list (to get these screenshots I created My Custom Theme).
⑹ Select your new theme from the list to look at all its files.
Boom! You have a custom theme. It has no files. It is basically a duplicate of whatever theme you were already using. Nothing scary about it. You could never, ever touch it and what you’d basically have is a duplicate of whichever builtin theme you have selected. That’s what you’re looking at up thar. I had Marfa selected so we get to see all the files inherited from Marfa. Below Marfa’s files you’ll find the default files that every theme gets to inherit, no matter-f$&king-what.
Just like in option two, we can selectively add files and totally not f$&k anything up … so long as we do not locate a new template in a path that obstructs the lookup of an inherited template we wanted to keep.
But for the file location we want to use, the steps from here are identical to steps ⑷ and ⑸ from option two. Let’s look at how we decide to name our file.
File Naming Conventions
The choice between TOML, YAML, and JSON (as described in option two) is still on the table. This choice will determine the file extension for our new template file. The convention I’ve come up with is to take what you’d get in option two and then replace the last forward-slash with an underscore. So, if our data file stored within the plugin’s directory was located at
data/plugin_cards/data.toml, we would create a new file in our custom theme locate at
data/plugin_cards_data.toml (I originally tried using the same location but the plugin file always overwrites the custom theme file in the merge process).
Here’s how my plugins look for the data they require. If data is found, any data located further down the lookup chain is ignored.
- Look for a file located at
- Look for a file located at
- Look for a parameter value entered using the plugin parameter interface
If the plugin’s GitHub repository is named
plugin-cards, this value would be
You’ll find this value in the plugin’s README. You needn’t worry about extensions, the plugin does not need to know the extension. So long as it is a valid JSON, YAML, or TOML file, Hugo resolves that sh$t automatically. I have also taken to including a commented template file within the plugin. You may just need to find and edit it, kinda like this one from plugin-favicons:
Or this one from plugin-lightbox:
Or this one from plugin-social-media-links:
You get the idea. Peace out. ☾𐂂