doc/ikiwiki/preprocessordirective.mdwn

   1 Preprocessor directives are similar to a [[WikiLink]] in form, except they
   2 begin with `!` and may contain parameters. The general form is:
   3
   4         \[[!directive param="value" param="value"]]
   5
   6 This gets expanded before the rest of the page is processed, and can be used
   7 to transform the page in various ways.
   8
   9 The quotes around values can be omitted if the value is a simple word.
  10 Also, some directives may use parameters without values, for example:
  11
  12         \[[!tag foo]]
  13
  14 A preprocessor directive does not need to all be on one line, it can be
  15 wrapped to multiple lines if you like:
  16
  17         \[[!directive foo="baldersnatch"
  18         bar="supercalifragalisticexpealadocious" baz=11]]
  19
  20 Also, multiple lines of *quoted* text can be used for a value.
  21 To allow quote marks inside the quoted text, delimit the block
  22 of text with triple-quotes:
  23
  24         \[[!directive text="""
  25         1. "foo"
  26         2. "bar"
  27         3. "baz"
  28         """]]
  29
  30 ikiwiki also has an older syntax for preprocessor directives, which requires a
  31 space in directives to distinguish them from [[wikilinks|wikilink]].  This
  32 syntax has several disadvantages: it requires a space after directives with no
  33 parameters (such as `\[[!pagecount ]]`), and it prohibits spaces in
  34 [[wikilinks|wikilink]].  ikiwiki now provides the `!`-prefixed syntax shown
  35 above as the preferred alternative.  However, ikiwiki still supports wikis
  36 using the older syntax, if their setup files disable the `prefix_directives`
  37 option.  For backward compatibility with existing wikis, this option currently
  38 defaults to off, so ikiwiki uses the old directive syntax; however, future
  39 versions of ikiwiki will turn this on by default.