doc/plugins/contrib/admonition.mdwn

   1 [[!meta author="anarcat"]]
   2 [[!template id=plugin name=admonition author="[[anarcat]]"]]
   3 [[!tag type/chrome]]
   4
   5 # Admonitions
   6
   7 This plugin adds directives that allow users to outline certain
   8 sections of text using a custom style sheet and bright icons.
   9
  10 5 directives are available:
  11
  12 * [[ikiwiki/directive/tip]]
  13 * [[ikiwiki/directive/note]]
  14 * [[ikiwiki/directive/important]]
  15 * [[ikiwiki/directive/caution]]
  16 * [[ikiwiki/directive/warning]]
  17
  18 Or, in Ikiwiki markup:
  19
  20     \[[!tip "Lorem ipsum dolor sit amet, consectetuer adipiscing elit."]]
  21     \[[!note "Vivamus id enim."]]
  22     \[[!important "In id erat non orci commodo lobortis."]]
  23     \[[!caution "In id erat non orci commodo lobortis."]]
  24     \[[!warning "Phasellus neque orci, porta a, aliquet quis, semper a, massa."]]
  25
  26 Those directives simply create a `<div>` elements in the right
  27 style. So the above can also be simply written as:
  28
  29     <div class="tip">Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</div>
  30     <div class="note">Vivamus id enim.</div>
  31     <div class="important">In id erat non orci commodo lobortis.</div>
  32     <div class="caution">In id erat non orci commodo lobortis.</div>
  33     <div class="warning">Phasellus neque orci, porta a, aliquet quis, semper a, massa.</div>
  34
  35 # Rationale
  36
  37 The idea behind the directives is to make the the CSS elements easier
  38 to discover through the builtin documentation. Obviously, more
  39 admonitions can be created simply by adding similar icons and CSS
  40 elements. Of course, you will not get the above directives expanded
  41 automatically unless you patch the admonition plugin, unfortunately.
  42
  43 # Code
  44
  45 [[!template id=gitbranch branch=anarcat/admonitions author="[[anarcat]]"]]
  46
  47 The [[!taglink patch]] is available from
  48 [anarcat's "admonition" branch][] and is designed to be merged in
  49 Ikiwiki directly:
  50
  51     git clone -b admonitions git://src.anarc.at/ikiwiki.git
  52
  53 [anarcat's "admonition" branch]: http://src.anarc.at/ikiwiki.git/shortlog/refs/heads/admonitions
  54
  55 See also [[todo/admonitions]] for the discussion leading to the
  56 creation of this plugin.