doc/todo/admonitions.mdwn

   1 In the [MoinMoin wiki][], there is this neat little hack called
   2 [Admonitions][] that basically create a `<div>` block with a specific
   3 style out of a certain section of the text.
   4
   5 I couldn't find a way to do this easily in Ikiwiki. On the one hand,
   6 there is no easy way to create div blocks with arbitrary styles (which
   7 is basically what MoinMoin admonitions are). On the other hand, there
   8 are no neat little logos in stylesheets like there are in Moinmoin
   9 either.
  10
  11 It would be great to see this implemented in Ikiwiki. Now, I know I
  12 can make a `<div>` myself, but I am not sure we should encourage users
  13 to inject arbitrary HTML in ikiwiki pages. And even then, we should
  14 add adminition CSS classes to make that easier to use.
  15
  16 Ideally, Ikiwiki would support Pandoc or Github-style fenced blocks
  17 and could abuse those to allow arbitrary styles (and markup!) to kick
  18 in. The [[ikiwiki/directive/format]] directive could also be used, I
  19 guess, but I dislike how it requires all those brackets and quotes and
  20 bangs and all...
  21
  22 -- [[anarcat]]
  23
  24 [MoinMoin wiki]: https://moinmo.in/
  25 [Admonitions]: https://moinmo.in/HelpOnAdmonitions
  26
  27 > ikiwiki's general design is that it supports exactly three forms
  28 > of markup:
  29 >
  30 > * whatever the `htmlize` plugin does
  31 > * as a special ikiwiki-specific extension, \[[wikilinks]]
  32 > * as another special ikiwiki-specific extension, \[[!directives]]
  33 >
  34 > All markup interpretation beyond wikilinks and directives is
  35 > the `htmlize` plugin's responsibility. The `mdwn` plugin
  36 > interprets Markdown, the `rst` plugin interprets
  37 > reStructuredText and so on.
  38 >
  39 > It sounds as though you're asking for a `htmlize` plugin which
  40 > interprets an extended dialect of Markdown:
  41 >
  42 > * standard Markdown (inasmuch as such a thing exists) as usual
  43 > * mapping certain syntax (what?) to "admonitions"
  44 >
  45 > ikiwiki deliberately doesn't implement Markdown parsing, it just
  46 > calls out to one of several Perl implementations of Markdown.
  47 >
  48 > Alternatively, you could have a small plugin that translates
  49 >
  50 >     [[!warning "Do what I say, not as I do."]]
  51 >
  52 > into an appropriate `<div>`. That's the "lightest" form of
  53 > markup that is built into ikiwiki itself.
  54 >
  55 > Alternatively^2, some different hook (I think [[plugins/typography]]
  56 > might use the right one?) could interpret an ad-hoc syntax and
  57 > turn it into a `<div>` either before or after `htmlize` processing.
  58 > However, that would be adding an extra layer of syntax for your
  59 > users to keep track of.
  60 >
  61 > [[templates|ikiwiki/directive/template]] are another way this could
  62 > work:
  63 >
  64 >     \[[!template id=warning text="Do as I say, not as I do."]]
  65 >
  66 > There's a "note" template bundled with ikiwiki already.
  67 >
  68 > --[[smcv]]
  69
  70 >> I think you mean the `htmlize` hook, as I cannot find any `htmlize`
  71 >> plugin.. That said, yeah, i understand the limitations of Ikiwiki
  72 >> here. I guess that the [[ikiwiki/directive/template]] directive is a
  73 >> good workaround, but it's not really shorter to write:
  74 >>
  75 >>     \[[!template id=warning text="Do as I say, not as I do."]]
  76 >>
  77 >> than to write:
  78 >>
  79 >> [[!format txt """<div class="warning">Do as I say, not as I do.</div>"""]]
  80 >>
  81 >> ... in fact, it's actually longer. So short of allowing arbitrary
  82 >> classes *and* fenced blocks, I don't think this can go much
  83 >> further.
  84 >>
  85 >> We *could*, however, import the admonition styles from MoinMoin
  86 >> directly. It would involve importing 5 icons from MoinMoin and
  87 >> creating associated styles. Is that something you would be open to?
  88 >>
  89 >> --[[anarcat]]
  90
  91 >> Looking more at the MoinMoin images, the source (and license!) for
  92 >> them is not quite clear, so they don't make such great targets for
  93 >> inclusion. They are, nevertheless, included in Debian so presumably
  94 >> they are DFSG-friendly? The copyright file marks them as "UNKNOWN"
  95 >> which is worrisome... I have found the following results about them:
  96 >>
  97 >> * [admon-warning.png][] seems to be [public domain according to this sketchy site][]
  98 >> * [admon-note.png][] seems to have a [source in XFCE][], as part of
  99 >>   the notes plugin
 100 >> * [admon-tip.png][] is used in the Debian release notes, so is
 101 >presumably fine as well [source there](https://www.debian.org/releases/testing/amd64/release-notes/images/note.png)
 102 >> * [admon-important.png][], same, [important.png](https://www.debian.org/releases/testing/amd64/release-notes/images/important.png)
 103 >> * [admon-caution.png][] can be found in Mediawiki as well, which is
 104 >> a good source of icons. According to Debian, some are public domain,
 105 >> some are LGPL (!?). In MediaWiki itself, the source of that file is
 106 >> lost in the mists of time.
 107 >>
 108 >> Even though there is some confusion about the source of those
 109 >> images, I think, in good faith, that they can be generally be
 110 >> considered reusable. --[[anarcat]]
 111
 112 [public domain according to this sketchy site]: http://all-free-download.com/free-vector/download/tango_process_stop_115912.html
 113 [source in XFCE]: http://git.xfce.org/panel-plugins/xfce4-notes-plugin/tree/data/icons/scalable/xfce4-notes-plugin.svg
 114 [admon-warning.png]: https://moinmo.in/moin_static19/modernized/img/admon-warning.png
 115 [admon-note.png]: https://moinmo.in/moin_static19/modernized/img/admon-note.png
 116 [admon-tip.png]: https://moinmo.in/moin_static19/modernized/img/admon-tip.png
 117 [admon-important.png]: https://moinmo.in/moin_static19/modernized/img/admon-important.png
 118 [admon-caution.png]: https://moinmo.in/moin_static19/modernized/img/admon-caution.png
 119
 120 Update: I have made a [[plugins/contrib/admonition]] plugin for this
 121 purpose, as a patch. Hopefully it will be mergeable here? Here's a
 122 screenshot of what the help page would look like, to give you an idea
 123 of the results:
 124
 125 <img src="http://paste.anarc.at/snaps/snap-2016.04.15-18.07.39.png" />