]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blob - doc/bugs/footnotes-look-weird.mdwn
(no commit message)
[git.ikiwiki.info.git] / 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.
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. :)
9 The following stylesheet should be added to `style.css`:
11     a.footnote { vertical-align: super; font-size: xx-small; }
12     div.footnotes { font-size: small; }
14 This is a typical style that user-agents apply to the `<sup>` tag. For
15 example, chromium has this builtin style for `<sup>`:
17     vertical-align: super;
18     font-size: smaller;
20 Bootstrap uses this instead:
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     }
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.
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]]
42 [this Stack Overflow discussion]: http://stackoverflow.com/questions/501671/superscript-in-css-only
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]]
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 >>> Discount enables enough features by default that adding footnotes doesn't
80 >>> seem bad to me. I'm also tempted by something like
81 >>>
82 >>> ```
83 >>> mdwn_enable: [footnotes]
84 >>> mdwn_disable: [alphalist, superscript]
85 >>> ```
86 >>>
87 >>> where the default for anything that was neither specifically enabled
88 >>> nor specifically disabled would be to enable everything that we don't
89 >>> think is a poor fit for the processing model (pandoc-style document
90 >>> headers) or likely to trigger by mistake (typographic quotes and
91 >>> [[maybe alpha lists|forum/"S."_gets_replace_by_"a."_in_my_ikiwiki]]).
92 >>> --[[smcv]]
93 >>>
94 >>>> Makes perfect sense to me. --[[anarcat]]
95 >>>>
96 >>>>> I have now enabled footnotes in Discount by default, with a new
97 >>>>> `mdwn_footnotes` option that can switch them off if they become
98 >>>>> problematic. --[[smcv]]
99 >>>
100 >> For example, to enable footnotes, one needs to call Discount like this:
101 >> 
102 >>       Text::Markdown::Discount::markdown($text, Text::Markdown::Discount::MKD_EXTRA_FOOTNOTE())
103 >>
104 >> That being said, Discount generates proper semantic markup when
105 >> footnotes, so this bug doesn't apply to the default Discount mode,
106 >> if we ignore the fact that it doesn't support footnotes at all.
107 >> Should I open a todo about this and the above?
108 >>
109 >> Also, it seems this *is* a bug with multimarkdown - I have
110 >> [reported the issue there](https://github.com/bobtfish/text-multimarkdown/issues/30).
111 >>
112 >> In the meantime, wouldn't it be better to have some styling here to
113 >> workaround the problem in MMD?
114 >>
115 >>> Honestly, I'd rather have ikiwiki's level of support for the non-preferred
116 >>> Markdown implementation be: if you are stuck on a platform with no C compiler
117 >>> or Perl headers, you can use the pure-Perl Markdown flavours, and they
118 >>> will sort of mostly work (but might not look great).
119 >>>
120 >>> I'm a little concerned that styling these rather generically-named classes
121 >>> might interfere with the implementations of footnotes in other Markdown
122 >>> implementations, or indeed non-Markdown - I wouldn't want to style
123 >>> `a.footnote` if the HTML produced by some other htmlize hook was
124 >>> `<sup><a class="footnote" ...>[1]</a></sup>` for instance.
125 >>> But they're probably harmless.
126 >>>
127 >>>> Alright, your call. :) At least this bug will be available as a workaround
128 >>>> for others that stumble upon the same problem! :) --[[anarcat]]
130 Note that I also make the bottom `<div>` small as well so that it has
131 less weight than the rest of the text. -- [[anarcat]]