In retrospect, I should have known there was going to be a problem. It seemed like such a simple thing, after all. I just wanted to switch to YAML to define my post front matter. YAML, which stands for YAML Ain’t Markup Language, has a very simple job: it provides a structure for keyed data (or metadata) that is human readable and portable1. Even more importantly, my markdown editor (Typora) has this neat little feature that lets me set up a YAML front matter section right in the post. It is a nice little bonus in what is, already, a gorgeous markdown editor.
The Python Markdown processor that Pelican uses doesn’t require YAML, but I prefer it for cross-compatibility with other platforms and processors (pandoc, Jekyll, etc). Luckily, there was a YAML plugin already designed for Pelican, so I decided to check it out. I won’t deny that I was a bit dubious about the plugin. It has been quite a while since it was updated. Nevertheless, I added it to my config and set it to build.
I expect this from time to time. One of the real joys of working with open tools is that they sometimes require a little work and understanding, and I like taking that time. It’s also a great way to learn about Python and its libraries. So, I dug in and starting picking apart the code that was (thankfully) fairly short. Of course, after two hours of work, I began to realize that I was diving into a rabbit hole. There was a very real risk that I was going to get lost there.
Before that happened, I needed to take a step back and really examine my problem.
- What functionality did I need actually need?
When I thought about it, I realized my needs were rather simple. I was looking for full YAML support, but none of my posts require this. All I want is to be able to use YAML delimiters and data value pairs in my front matter. What I discovered is that I could already do that. Both of these options are supported by the existing Markdown Meta extension that is included with the Markdown processor. I don’t get true YAML support, but for my current needs it works extremely well. It lets me focus on the work I should be doing, and that is the point.
Working with technology is about looking to your story. Agile development practices often frame features and needs in terms of the user story, but these stories are just as important when we think about our hardware and software choices. In our own use and practice we should be thinking about our own user stories. How will you use your technology? Why do you have it? Yes, we often need tools that help us to achieve our goals. There is, no doubt, that diving into those rabbit holes is sometimes absolutely needed, but we too easily forget functionality is about more than quantity. It is about reaching the desired goal. Is that where you are headed?