Philipp Trommler's Blog - pythonhttps://blog.philipp-trommler.me/en/2019-09-29T21:42:06+02:00I've Made A Thing: yafg2019-09-29T21:42:06+02:002019-09-29T21:42:06+02:00Philipp Trommlertag:blog.philipp-trommler.me,2019-09-29:/en/posts/2019/09/29/imat-yafg/<p>Dissatisfied with the existing solutions, I've made my own Markdown
plugin for creating <code><figure></code> and <code><figcaption></code> tags for pictures:
<em>yafg</em>. Here's why and how.</p><p>As I've mentioned <a href="https://blog.philipp-trommler.me/en/posts/2019/08/09/my-new-blog/">in my first article on my new
blog</a>, I was unable to find a – for my
needs – working Markdown plugin that wraps proper <code><figure></code> and
<code><figcaption></code> tags around my images. One of them used a strange syntax, another
one used the <code>alt</code> 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.</p>
<p>All in all a dissatisfying situation, especially since I think that semantic
HTML tags like <code><figure></code> and <code><figcaption></code> are really important because of
accessibility, which is, by the way, also the reason why using the <code>alt</code>
attribute for the caption is bad. The <code>alt</code> 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 <a href="https://html.spec.whatwg.org/multipage/images.html#alt">HTML standard</a> puts
it:</p>
<blockquote>
<p>"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."</p>
</blockquote>
<p>(at least for the most prominent (content-wise) images which are likely the ones
you want to surround with <code><figure></code> 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 <code>title</code>
attribute in turn has no <em>real</em> meaning more than a vague "[…] information […]
appropriate for a tooltip" and <a href="https://html.spec.whatwg.org/multipage/dom.html#the-title-attribute">its usage is
discouraged</a>.
Thus, it's an ideal candidate to hold the caption.</p>
<p>And here's where <a href="https://git.sr.ht/~ferruck/yafg"><em>yafg</em></a> comes into play: It
wraps all freestanding images in <code><figure></code> tags and uses the images' titles to
form an appropriate <code><figcaption></code>. Of course it supports multiline captions so
you can format your Markdown files as wanted. Additionally, you can strip the
<code>title</code> 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
<code>Treeprocessor</code> instead of working with always-breaking regular expressions.</p>
<p>One small update that I've planned for the future is that you can add custom
classes to both the <code><figure></code> and the <code><figcaption></code> tags for styling and
scripting purposes. But that has to wait for now, probably until I need it
myself 😉.</p>
<p>If you want to try out <em>yafg</em> yourself, you can install it via
<a href="https://pypi.org/project/yafg/">PyPI</a>. 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!</p>