In the MoinMoin wiki, there is this neat little hack called Admonitions that basically create a <div> block with a specific style out of a certain section of the text.

I couldn't find a way to do this easily in Ikiwiki. On the one hand, there is no easy way to create div blocks with arbitrary styles (which is basically what MoinMoin admonitions are). On the other hand, there are no neat little logos in stylesheets like there are in Moinmoin either.

It would be great to see this implemented in Ikiwiki. Now, I know I can make a <div> myself, but I am not sure we should encourage users to inject arbitrary HTML in ikiwiki pages. And even then, we should add adminition CSS classes to make that easier to use.

Ideally, Ikiwiki would support Pandoc or Github-style fenced blocks and could abuse those to allow arbitrary styles (and markup!) to kick in. The format directive could also be used, I guess, but I dislike how it requires all those brackets and quotes and bangs and all...

-- anarcat

ikiwiki's general design is that it supports exactly three forms of markup:

  • whatever the htmlize plugin does
  • as a special ikiwiki-specific extension, [[wikilinks]]
  • as another special ikiwiki-specific extension, [[!directives ]]

All markup interpretation beyond wikilinks and directives is the htmlize plugin's responsibility. The mdwn plugin interprets Markdown, the rst plugin interprets reStructuredText and so on.

It sounds as though you're asking for a htmlize plugin which interprets an extended dialect of Markdown:

  • standard Markdown (inasmuch as such a thing exists) as usual
  • mapping certain syntax (what?) to "admonitions"

ikiwiki deliberately doesn't implement Markdown parsing, it just calls out to one of several Perl implementations of Markdown.

Alternatively, you could have a small plugin that translates

[[!warning  "Do what I say, not as I do."]]

into an appropriate <div>. That's the "lightest" form of markup that is built into ikiwiki itself.

Alternatively2, some different hook (I think typography might use the right one?) could interpret an ad-hoc syntax and turn it into a <div> either before or after htmlize processing. However, that would be adding an extra layer of syntax for your users to keep track of.

templates are another way this could work:

[[!template  id=warning text="Do as I say, not as I do."]]

There's a "note" template bundled with ikiwiki already.

--smcv

I think you mean the htmlize hook, as I cannot find any htmlize plugin.. That said, yeah, i understand the limitations of Ikiwiki here. I guess that the template directive is a good workaround, but it's not really shorter to write:

[[!template  id=warning text="Do as I say, not as I do."]]

than to write:

<div class="warning">Do as I say, not as I do.</div>

... in fact, it's actually longer. So short of allowing arbitrary classes and fenced blocks, I don't think this can go much further.

We could, however, import the admonition styles from MoinMoin directly. It would involve importing 5 icons from MoinMoin and creating associated styles. Is that something you would be open to?

--anarcat

Looking more at the MoinMoin images, the source (and license!) for them is not quite clear, so they don't make such great targets for inclusion. They are, nevertheless, included in Debian so presumably they are DFSG-friendly? The copyright file marks them as "UNKNOWN" which is worrisome... I have found the following results about them:

Even though there is some confusion about the source of those images, I think, in good faith, that they can be generally be considered reusable. --anarcat

Update: I have made a ?admonition plugin for this purpose, as a patch. Hopefully it will be mergeable here? Here's a screenshot of what the help page would look like, to give you an idea of the results:

I like the idea of admonitions. I've done something vaguely similar on my own site (e.g.), but I just use \[[!template and put up with the verbosity.I like that \[[!tip is shorter than \[[!template id=…. If I was being a total purist I'd argue that the correct change would be to make a syntax shortcut for the template syntax, since functionally that's what tip is doing, and include the admonition styles in either style.css or in every shipped theme. But I'm more of a pragmatist and your current plugin actually exists and IkiWiki is starving for contributors (IMHO) so I encourage maintainers to merge it. I will probably merge it into opinionated ikiwiki in either case (which will at least mean there'll be another avenue for people to check it out) — Jon, 2020-08-07

One quick tip/request, anarcat: If you could update the "master" branch in your IkiWiki fork to match the merge base for your branches, it would be easy to use Gitlab's "compare" feature in-browser to see a combined diff of your changes. — Jon, 2020-08-07

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 anarcat and my maintenance log. I hope that helps! -- anarcat

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

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 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 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) was a much earlier commit than d0099568, so "Compare" would include all the unrelated upstream changes. If instead either master was d0099568, or 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 git incantation. — Jon, 2020-08-12

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, toc-skip, page-template-variable, js-newline, i18n-headinganchors, dev/git-annex-support, and geo-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

I've finally started playing around with this plugin. I think the default CSS needs tweaking. I see "warning" has padding to try to account for the icon size, but the other admonitions do not. Perhaps they need to inherit some style from a common class? Either way, the padding does not seem to work. This is a fresh ikiwiki with the actiontab theme enabled:

pic demoing admonitions — Jon, 2021-02-15

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. Obviously, the CSS does need more tweaking, but it seems it's not my specialty. ;) -- anarcat

It turned out to be a simple fix, a missing semicolon. patch here. The rest of that branch is just your admonitions branch rebased onto 3.20200202.3. —Jon, 2021-02-18

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

done. — Jon, 2025-02-22