Currently, the [[ikiwiki/directive/img]] directive creates a `<img>`
tag for images (which is fine) but also creates a traditional
`<table>` structure around it to show the caption when the `caption`
parameter is passed. This is less fine.

HTML5 introduced the `<figure>` element, and particularly the
[figcaption](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption) element, which is particularly relevant here. It is
not filtered by the html scrubber (or so it seems), so it's currently
possible to use it in Markdown documents already, like so:

    <figure>
    <img src="example.jpg" />
    <figcaption>Foo</figcaption>
    </figure>

This is standard and works well, except there are bits of style
missing, because Ikiwiki's stylesheet assumes its peculiar table image
layout. `doc/style.css`, for example, has this:

    .img caption {
            font-size: 80%;
            caption-side: bottom;
            text-align: center;
    }

... which is a good start to format tables, but is ineffective for
`figcaption`. In my tests, I have used this to good effect:

    .img caption, figcaption {
        text-align: center;
        /* assuming that relative size is more responsive than arbitrary percentages */
        font-size: smaller;
        caption-side: bottom;
    }

The `figcaption` stylesheet reuses the `<table>` semantics so the
above just works, as far as I can tell.

The final step would be to unmangle the `<img>` directive output. It
should output the above `<figure>` snippet if HTML5 is enabled in the
wiki.

Otherwise we might also want to get rid of the `<table>` stuff
anyways, as most examples out there use a `<div>` in HTML4. Here is an
[example from the W3C](https://www.w3.org/Style/Examples/007/figures.en.html#Illustrati) or [bootstrap](https://getbootstrap.com/docs/3.3/components/#thumbnails-custom-content). The former suggests
something like this:

    <div class="figure">
      <p><img src="example.jpg" />
      <p>Foo
    </div>

The CSS, in that case, would be simply:

    div.figure {
      text-align: center;
      font-size: smaller;
    }

The double-`<p>` is what allows pushing the caption upwards with CSS
in their later example, with this CSS:

    div.figure {
      display: table;
    }
    div.figure p + p {
      display: table-caption;
      caption-side: top;
    }

The `<div>` mechanism seems much simpler than the current table-based
markup. I'd be happy to provide patches to do the above if there's
interest. Considering that most of my images are hosted outside of
ikiwiki, I cannot use of the `img` directive in the first place so I
don't need to patch `img.pm` and don't want to carry yet another
delta... But I could sure use upstreaming the CSS fixes. ;)

Thanks! -- [[anarcat]]