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.
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
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.
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
24 [MoinMoin wiki]: https://moinmo.in/
25 [Admonitions]: https://moinmo.in/HelpOnAdmonitions
27 > ikiwiki's general design is that it supports exactly three forms
30 > * whatever the `htmlize` plugin does
31 > * as a special ikiwiki-specific extension, \[[wikilinks]]
32 > * as another special ikiwiki-specific extension, \[[!directives]]
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.
39 > It sounds as though you're asking for a `htmlize` plugin which
40 > interprets an extended dialect of Markdown:
42 > * standard Markdown (inasmuch as such a thing exists) as usual
43 > * mapping certain syntax (what?) to "admonitions"
45 > ikiwiki deliberately doesn't implement Markdown parsing, it just
46 > calls out to one of several Perl implementations of Markdown.
48 > Alternatively, you could have a small plugin that translates
50 > [[!warning "Do what I say, not as I do."]]
52 > into an appropriate `<div>`. That's the "lightest" form of
53 > markup that is built into ikiwiki itself.
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.
61 > [[templates|ikiwiki/directive/template]] are another way this could
64 > \[[!template id=warning text="Do as I say, not as I do."]]
66 > There's a "note" template bundled with ikiwiki already.
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:
75 >> \[[!template id=warning text="Do as I say, not as I do."]]
79 >> [[!format txt """<div class="warning">Do as I say, not as I do.</div>"""]]
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
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?
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:
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
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.
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]]
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
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
125 <img src="http://paste.anarc.at/snaps/snap-2016.04.15-18.07.39.png" />
129 I like the idea of admonitions. I've done something vaguely similar on my own site ([e.g.](https://jmtd.net/film/blade_runner/)), but I just
130 use `\[[!template` and put up with the verbosity.I like that `\[[!tip` is shorter than `\[[!template id=…`. If
131 I was being a total purist I'd argue that the correct change would be to make a syntax shortcut
132 for the template syntax, since functionally that's what `tip` is doing, and include the
133 admonition styles in either `style.css` or in every shipped theme. But I'm more of a pragmatist
134 and your current plugin actually exists and IkiWiki is starving for contributors (IMHO)
135 so I encourage maintainers to merge it. I will probably merge it into [opinionated ikiwiki](https://jmtd.net/log/opinionated_ikiwiki/)
136 in either case (which will at least mean there'll be another avenue for people to check it out) *— [[Jon]], 2020-08-07*
138 > One quick tip/request, [[anarcat]]: If you could update the "master" branch in your IkiWiki
139 > fork to match the merge base for your branches, it would be easy to use Gitlab's "compare"
140 > feature in-browser to see a combined diff of your changes. *— [[Jon]], 2020-08-07*
142 > > Thanks for your support and comments! :) I don't have the time to manage another extra branch on top of the stack I already have unfortunately. but it might be simpler for me in the future... I keep on hoping all patches get merged and that i don't need to (more officially) fork `master`, but it seems that's where I need to go myself... In the meantime you can see the list of patches I maintain in [[users/anarcat]] and [my maintenance log](https://anarc.at/services/wiki/). I hope that helps! -- [[anarcat]]
144 > > Turns out I found the time. I merged all my active branches in the `master` branch on gitlab. not sure what you'd compare it against, but there, it's done. :) [[anarcat]]
146 >>> Thanks for that! I'll try to explain what I meant in terms of an example. your `admonitions` is a series of commits that ultimately sit on top of
147 >>> upstream's `d0099568` ("Prepare release for unstable"). If I want to see a quick combined diff of all the changes made in that branch, I can try to
148 >>> use GitLab's "Compare" feature, but it does not let me specify a SHA to compare against, only a ref-name such as (your) `master`, which (at the time)
149 >>> was a much earlier commit than `d0099568`, so "Compare" would include all the unrelated upstream changes. If instead either `master` was `d0099568`, or
150 >>> `admonitions` was rebased on top of whatever your `master` was, then GitLab's "Compare" would be useful. As it is, I cloned locally and did the necessary
151 >>> `git` incantation. *— [[Jon]], 2020-08-12*
153 >>>> I have rebased all my current branches onto `debian/3.20190228-1` because that's what I'm patching in production, and I have updated my `master` branch on GitLab to follow that. The branches are admonitions, [bootstrap-plugin](https://ikiwiki.info/plugins/contrib/bootstrap), [toc-skip](https://ikiwiki.info/todo/allow_toc_to_skip_entries), [page-template-variable](https://ikiwiki.info/todo/include_page_variable_in_base_templates), [js-newline](https://ikiwiki.info/bugs/javascript_resources_placed_after_html_tag/), [i18n-headinganchors](https://ikiwiki.info/plugins/contrib/i18nheadinganchors), [dev/git-annex-support](https://ikiwiki.info/todo/git-annex_support/), and [geo-scheme](https://ikiwiki.info/todo/add_geo_uri_scheme/). Phew. Is that what you needed? It's still kind of a mess, but it should make it easier for you to review... --[[anarcat]]
157 I've finally started playing around with this plugin. I think the default CSS needs
158 tweaking. I see "warning" has `padding` to try to account for the icon size, but
159 the other admonitions do not. Perhaps they need to inherit some style from a common
160 class? Either way, the padding does not seem to work. This is a fresh ikiwiki with
161 the actiontab theme enabled:
163 <img src=https://jmtd.net/tmp/admonition.png alt="pic demoing admonitions" />
164 *— [[Jon]], 2021-02-15*
166 > I had kind of given up on this guy here, to be honest, but if you want to see a working version, you can look at [my sandbox](https://anarc.at/sandbox/). Obviously, the CSS does need more tweaking, but it seems it's not my specialty. ;) -- [[anarcat]]
168 >> It turned out to be a simple fix, a missing semicolon. [patch here](https://github.com/jmtd/ikiwiki/commit/3e31200ed258ba1f7ab1652d6bc2d035a9e5c990). The rest of that branch is just your admonitions branch rebased onto `3.20200202.3`. *—[[Jon]], 2021-02-18*
170 >>> Interesting. That was of course, a missing semicolon, not sure how I missed that. I cherry-picked your patch, but I wonder why I wasn't seeing the problem on my end... Maybe I had other padding that was covering for this... Thanks, in any case! :) -- [[anarcat]]