17. Figures and images

Suppose we want to illustrate our blog post with images or diagrams of some kind. Obviously there is nothing stopping us from generating some image files and plonking them in the pub directory where they can be referenced from img tags or ![…](…) constructs in the text. But can we do better?

Figures, captions and image descriptions

Let’s assume we want to be able to include an image with an optional caption in between or alongside two paragraphs of the post.

One way to mark this an image with caption in HTML is to use the figure element, like so:

<figure>
    <img src="pics/2026-03-08/elegant-gowns-1924.600.png" width=600 height=320
        alt="Fashion illustration">
    <figcaption>
        Illustrations of elegant gowns by Archibald Slugg for the <em>Lady’s Scrapbook</em> (1924).
    </figcaption>
</figure>

Wrapping the familiar img element in a figure tells modern browsers that the image and the caption go together, and hints at its relationship to the surrounding text. We expect that a screen reader will announce the image as something like ‘Image: Fashion illustration. Illustrations of elegant gowns by Archibald Slug for the Lady’s Scrapbook Nineteen Twenty Four.’

The alt-text (content of the alt attribute) in this case is a short description of what sort of image it is. If our fictional illustration is just adding colour to an article about Archie Slugg and his complicated relationship with the Lady’s Scrapbook, it is enough to just say it is an illustration and carry on with the next paragraph. If this were instead an image of text, of a poem in a page of Lady’s Scrapbook, let’s say, then the text should probably appear in the alt attribute.

Often we see people advocating for alt-text to be a complete image description. This is not always appropriate. The alt-text is a textural alternative to the image, which might or might not detail what it looks like, depending on context. A better place to put a detailed visual description is often the longdesc attribute, which links to a longer description. The problem with longdesc is that

• support by screen readers is inconsistent; and
• web browsers generally do not show it at all.

We should generally avoid include invisible accessibility data in pages, since what is not visible is easily forgotten when proof-reading the site. So the the image description should be visible on the page somewhere. We can, for example, incorporate it at the foot of the page as a kind of endnote. We can also include a visible link since browsers tend not to.

<figure id="elegant">
    <img src="pics/2026-03-08/elegant-gowns-1924.600.png" width=600 height=320
        alt="Fashion illustration" longdesc="#elegant-desc">
    <figcaption>
        Illustrations of elegant gowns by Archibald Slugg for the
        <i>Lady’s Scrapbook</i> (1924).
        <a href="#elegant-desc" class="desc-link">[Image description]</a>
    </figcaption>
</figure>
…
<h2>List of figures</h2>
<ol>
    <li id="elegant-desc">
        <a href="#elegant">Illustrations of elegant gowns by Archibald Slugg for the
        <i>Lady’s Scrapbook</i> (1924).</a>
        Colour fashion plate depicting an outdoor scene with three women, one of whom
        is sitting on a swing suspended between two trees that frame the scene.
        They are wearing the draped, low-waisted gowns in soft fabrics without the
        obvious padding or corsetry of Edwardian fashions. They have bobbed hair and
        long elegant figures with only subtle curves.
    </li>
    …
</ol>

We here are treating the long-desc like a footnote, where the reader can choose to skip over it or follow the link. If they follow the link they take a little detour where the image is described, with a link back to the text to resume reading from where they left off.

This is not the only approach. There is a discussion on complex images in the W3C Web Accessibility Initiative tutorials. Suggestions have been made involving HTML5 popups or HTML5 details/summary.

How can Mismiy help?

We can support this in Mismiy by allowing the inclusion of illustration metadata as part of the front matter of the page.

title: Archibald Sugg illustrating the fashions of the 1920s
figures:
  - id: elegant
    src: pics/2026-03-08/elegant-gowns-1924.600.png
    caption: Illustrations of elegant gowns by Archibald Slugg for the
        _Lady’s Scrapbook_ (1924).
    description: Colour fashion plate depicting an outdoor scene etc etc
  - id: winter
    src: pics/2026-03-08/winter-fashions-1924.600.png
    caption: Illustrations of winter fashions by Archibald Slugg for the
        _Lady’s Scrapbook_ (1924).
    description: Colour fashion plate depicting etc etc

In the early 1920s … blah blah … (start of first paragraph)

The source URL is required, the other fields can be omitted if the writer does not mind the default.

Having defined image metadata, how do we incorporate it in to the text? We will use the default image-insertion tag provided by Markdown.

…
Blah blah blah paragraph paragraph.

![Fashion illustration](elegant)

Next paragraph blah blah blort.

This supplies the alt-text Fashion illustration (which presumably is useful for reminding the author why they put it here) and the short code from the list of figures.

When Mismiy uses the Markdown processor Mistletoe to translate the article, this fragment turns in to an HTML fragment like <p><img src="elegant" alt="Fashion illustration"></p>. Armed with the list of figures from the front of the file, Mismiy scans for that pattern in the HTML, extracts the image identifier and alt text, retrieve a the metadata for the figure, and then expands a partial template figure.html that generates the replacement HTML for the figure.

The template figure.html might look like this:

<figure id="{{id}}">
    <img alt="{{alt}}"{{#description}} longdesc="#{{id}}-desc"{{/description}}
        {{#width}}width={{.}} {{/width}}{{#height}}height={{.}} {{/height}}src="{{src}}"{{#srcset}}
        srcset="{{srcset}}"{{/srcset}}{{#description}}
        longdesc="#{{id-desc}}"{{/description}}>{{#caption}}
    <figcaption>
       {{{caption_html}}}{{#description}}
       <a href="#{{id}}-desc" class="desc-link">[Image description]</a>{{/description}}
    </figcaption>{{/caption}}
</figure>

The partial sees the metadata for the figure in question, and also an extra fields caption_html and description_html, so it is possible to use Markdown in these the corresponding fields. The HTML code is not wrapped in a <p>…</p> tag.

The metadata for all the figures is also exposed in the template context, so as to be handy for the template to generate the list of figures at the end of the page.

Support for high-definition images

Given modern high-density displays and screen sizes ranging from phone to giant monitors, a responsive page will have differently scaled versions of an image for the browser to choose from. One way to do this with modern HTML is to add a srcset attribute to the img tag listing the higher-resolution versions of the image:

<figure>
    <img src="pics/2026-03-08/elegant-gowns-1924.600.png" width=600 height=320
        srcset="pics/2026-03-08/elegant-gowns-1924.1800.png 3x, pics/2026-03-08/elegant-gowns-1924.1200.png 2x"
        alt="Fashion illustration">
    <figcaption>
        Illustrations of elegant gowns by Archibald Slugg for the
        <i>Lady’s Scrapbook</i> (1924).
    </figcaption>
</figure>

The src and srcset attribute values together provide a map from pixel density to URL. We can provide that in the image metadata on the page as a single lookup:

title: Archibald Sugg illustrating the fashions of the 1920s
figures:
  - id: elegant
    src:
        1x: pics/2026-03-08/elegant-gowns-1924.600.png
        2x: pics/2026-03-08/elegant-gowns-1924.1200.png
        3x: pics/2026-03-08/elegant-gowns-1924.1800.png
…

The Mismiy generator will create a srcset value if it is needed. The template figure.html can then include this if it is defined.

The StrictYAML parser we use in Mismiy allows us to specify in the schema that src is either a string or is a map like the above.

Out of scope (for now): asset handling

For the generated HTML to work these src URLs must reference the image files, which we can arrange by copying the .png or .jpeg files in to a directory within the static directory so they get copied in to pub when the site is built.

This in turn implies the existence of some kind of image pipeline that takes the master image and exports the web-optimized versions in the resolutions needed. There are many options, such as Shortcuts + Acorn, or a shell script using ImageMagick. While we could add code to Mismiy to do a simple resize-and-convert pipeline it would be hard to make one with sufficient flexibility that wasn’t harder to set up than one of the above. The one advantage it would have is it could eliminate the need for coordinating src fields in posts with file names on disk.

A future iteration on tis feature address the problem of keeping the URL references in the posts and the file names of the image assets in sync—perhaps by having Mismiy search for image files in the appropriate directory and introspect the images to find their dimensions, and hence find the src, width, and height fields without the author needing to supply them.