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!