Philipp Trommler's Blog

I've Made A Thing: yafg

Dissatisfied with the existing solutions, I've made my own Markdown plugin for creating <figure> and <figcaption> tags for pictures: yafg. Here's why and how.

Published by Philipp Trommler. This article has also been translated to: de.

As I've mentioned in my first article on my new blog, I was unable to find a – for my needs – working Markdown plugin that wraps proper <figure> and <figcaption> tags around my images. One of them used a strange syntax, another one used the alt attribute for generating the caption (more on that later) and a third one was additionally broken in a way that it couldn't handle multiline captions.

All in all a dissatisfying situation, especially since I think that semantic HTML tags like <figure> and <figcaption> are really important because of accessibility, which is, by the way, also the reason why using the alt attribute for the caption is bad. The alt is meant as an alternative (hence the name) representation of the element carrying the attribute to make it accessible to those who otherwise cannot access it for one reason or another. As the HTML standard puts it:

"One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present. Whatever you say instead of the image is typically a good start for writing the alternative text."

(at least for the most prominent (content-wise) images which are likely the ones you want to surround with <figure> tags). A caption – on the other hand – is more like a paraphrase, maybe naming and citing additional sources and giving an interpretation (in my understanding). The title attribute in turn has no real meaning more than a vague "[…] information […] appropriate for a tooltip" and its usage is discouraged. Thus, it's an ideal candidate to hold the caption.

And here's where yafg comes into play: It wraps all freestanding images in <figure> tags and uses the images' titles to form an appropriate <figcaption>. Of course it supports multiline captions so you can format your Markdown files as wanted. Additionally, you can strip the title attribute from the image so you don't have to add it to your HTML if you otherwise wouldn't do it. To achieve this, it implements a Markdown Treeprocessor instead of working with always-breaking regular expressions.

One small update that I've planned for the future is that you can add custom classes to both the <figure> and the <figcaption> tags for styling and scripting purposes. But that has to wait for now, probably until I need it myself 😉.

If you want to try out yafg yourself, you can install it via PyPI. Short notes on how to use it in plain Python as well as in Pelican can be found in the README. Good luck and feedback is welcome!

Filed under I've Made A Thing. Tags: python, markdown, yafg.

Want to comment on this article? Write me at blog [at] philipp-trommler [dot] me!

Articles from blogs I follow around the net

Our Ethics, Not Yours
via /dev/lawyer, September 28, 2019

I like Matt Asay, but his open source is very different from mine. In a recent post, Matt offers a bald rebuke of developers yanking code or changing license terms to protest organizations doing things they abhor, like the United States’ Immigrations and …

Our ignorance about gravity
via Aeon, September 27, 2019

Isaac Newton’s law of universal gravitation is many things – revolutionary, elegant, mysterious – but, as it turns out, one thing we know for sure is that it’s not, well, universal. On the scale of our solar system, Newton’s observation – that objects att…

A command-line "Countdown" (UK) companion
via BASHing data, September 27, 2019

Fast solver for anagram puzzles, and a puzzle generator

Generated by openring