doc/bugs/footnotes-look-weird.mdwn

   1 Multimarkdown footnotes are pretty useful. If they are enabled in a
   2 wiki, they don't look so good with the default stylesheet, however, as
   3 the references are in the same size and positioning as everything
   4 else.
   5
   6 This particular wiki does not use multimarkdown, so there's no easy
   7 way to demonstrate this here, you'll have to trust me on this. :)
   8
   9 The following stylesheet should be added to `style.css`:
  10
  11     a.footnote { vertical-align: super; font-size: xx-small; }
  12     div.footnotes { font-size: small; }
  13
  14 This is a typical style that user-agents apply to the `<sup>` tag. For
  15 example, chromium has this builtin style for `<sup>`:
  16
  17     vertical-align: super;
  18     font-size: smaller;
  19
  20 Bootstrap uses this instead:
  21
  22     sup {
  23         top: -.5em;
  24     }
  25
  26     sub, sup {
  27         position: relative;
  28         font-size: 75%;
  29         line-height: 0;
  30         vertical-align: baseline;
  31     }
  32
  33 I settled on `xx-small` because it's the only size that doesn't affect
  34 line-height here. However, Bootstrap's way may be better.
  35
  36 At any rate, the correct way to fix this is to *avoid* custom styling
  37 and use the `<sup>` tag for the footnote reference, as it has
  38 *meaning* which is important to have proper semantic output (e.g. for
  39 screen readers), as detailed in [this Stack Overflow discussion][].
  40 --[[anarcat]]
  41
  42 [this Stack Overflow discussion]: http://stackoverflow.com/questions/501671/superscript-in-css-only
  43
  44 > ikiwiki code does not interpret Markdown or translate it into HTML.
  45 > If I'm interpreting what you say correctly, you seem to be implying
  46 > that you think [[!cpan Text::MultiMarkdown]] is producing incorrect
  47 > HTML for footnotes (is an `<a>` with a `class`, should be a `<sup>`).
  48 > If so, please report that as a MultiMarkdown bug, not an ikiwiki bug,
  49 > or alternatively don't use MultiMarkdown.
  50 >
  51 > The recommended backend for the [[plugins/mdwn]] plugin is
  52 > [[!cpan Text::Markdown::Discount]], which optionally implements
  53 > footnotes using the same syntax as MultiMarkdown (originating in
  54 > "PHP Markdown Extra"). However, ikiwiki doesn't currently enable
  55 > that particular feature. Maybe it should, at least via a site-wide
  56 > option.
  57 >
  58 > What remains after eliminating the MultiMarkdown bug seems to be:
  59 > ikiwiki's default stylesheet does not contain the necessary styling
  60 > to work around the non-semantic markup produced by the non-default
  61 > Text::MultiMarkdown Markdown implementation. Is that an accurate
  62 > summary?
  63 > --[[smcv]]
  64
  65 >> That is an accurate summary.
  66 >>
  67 >> I didn't realize that Discount didn't actually support footnotes in
  68 >> Ikiwiki by default. I guess I enabled Multimarkdown exactly for that
  69 >> kind of stuff that was missing...  It seems to me it would be
  70 >> reasonable to enable footnotes in Ikiwiki. There's already a lot of
  71 >> stuff that Discount does that is way more exotic (e.g. tables) and
  72 >> non-standard (e.g. `abbr:`).
  73 >>
  74 >> Ideally, users would get to configure which
  75 >> [Discount flags](http://www.pell.portland.or.us/~orc/Code/markdown/#flags)
  76 >> are enabled in their configuration, but I understand that makes the
  77 >> configuration more complicated and error-prone.
  78 >>
  79 >> For example, to enable footnotes, one needs to call Discount like this:
  80 >>
  81 >>       Text::Markdown::Discount::markdown($text, Text::Markdown::Discount::MKD_EXTRA_FOOTNOTE())
  82 >>
  83 >> That being said, Discount generates proper semantic markup when
  84 >> footnotes, so this bug doesn't apply to the default Discount mode,
  85 >> if we ignore the fact that it doesn't support footnotes at all.
  86 >> Should I open a todo about this and the above?
  87 >>
  88 >> Also, it seems this *is* a bug with multimarkdown - I have
  89 >> [reported the issue there](https://github.com/bobtfish/text-multimarkdown/issues/30).
  90 >>
  91 >> In the meantime, wouldn't it be better to have some styling here to
  92 >> workaround the problem in MMD?
  93
  94 Note that I also make the bottom `<div>` small as well so that it has
  95 less weight than the rest of the text. -- [[anarcat]]