2cb602ebe114151a85ca59f44890b3cf236fe00b
[ikiwiki.git] / 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 the `prefix_directives` option is not enabled.
37 For backward compatibility with existing wikis, this option currently
38 defaults to off, so ikiwiki supports the old syntax.