doc/todo/html5_image_captions.mdwn

   1 Currently, the [[ikiwiki/directive/img]] directive creates a `<img>`
   2 tag for images (which is fine) but also creates a traditional
   3 `<table>` structure around it to show the caption when the `caption`
   4 parameter is passed. This is less fine.
   5
   6 HTML5 introduced the `<figure>` element, and particularly the
   7 [figcaption](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption) element, which is particularly relevant here. It is
   8 not filtered by the html scrubber (or so it seems), so it's currently
   9 possible to use it in Markdown documents already, like so:
  10
  11     <figure>
  12     <img src="example.jpg" />
  13     <figcaption>Foo</figcaption>
  14     </figure>
  15
  16 This is standard and works well, except there are bits of style
  17 missing, because Ikiwiki's stylesheet assumes its peculiar table image
  18 layout. `doc/style.css`, for example, has this:
  19
  20     .img caption {
  21             font-size: 80%;
  22             caption-side: bottom;
  23             text-align: center;
  24     }
  25
  26 ... which is a good start to format tables, but is ineffective for
  27 `figcaption`. In my tests, I have used this to good effect:
  28
  29     .img caption, figcaption {
  30         text-align: center;
  31         /* assuming that relative size is more responsive than arbitrary percentages */
  32         font-size: smaller;
  33         caption-side: bottom;
  34     }
  35
  36 The `figcaption` stylesheet reuses the `<table>` semantics so the
  37 above just works, as far as I can tell.
  38
  39 The final step would be to unmangle the `<img>` directive output. It
  40 should output the above `<figure>` snippet if HTML5 is enabled in the
  41 wiki.
  42
  43 Otherwise we might also want to get rid of the `<table>` stuff
  44 anyways, as most examples out there use a `<div>` in HTML4. Here is an
  45 [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
  46 something like this:
  47
  48     <div class="figure">
  49       <p><img src="example.jpg" />
  50       <p>Foo
  51     </div>
  52
  53 The CSS, in that case, would be simply:
  54
  55     div.figure {
  56       text-align: center;
  57       font-size: smaller;
  58     }
  59
  60 The double-`<p>` is what allows pushing the caption upwards with CSS
  61 in their later example, with this CSS:
  62
  63     div.figure {
  64       display: table;
  65     }
  66     div.figure p + p {
  67       display: table-caption;
  68       caption-side: top;
  69     }
  70
  71 The `<div>` mechanism seems much simpler than the current table-based
  72 markup. I'd be happy to provide patches to do the above if there's
  73 interest. Considering that most of my images are hosted outside of
  74 ikiwiki, I cannot use of the `img` directive in the first place so I
  75 don't need to patch `img.pm` and don't want to carry yet another
  76 delta... But I could sure use upstreaming the CSS fixes. ;)
  77
  78 Thanks! -- [[anarcat]]