Mercurial > wikked

annotate docs/pages/04_syntax.md @ 396:2a70f537337d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added tag 0.6.6 for changeset fcd6caf13cf7
author Ludovic Chabant <ludovic@chabant.com>
date Thu, 15 Oct 2015 23:39:17 -0700
parents 3a61f45702cb
children dcaa41b39c23
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Syntax
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 icon: pencil
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4 ---
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 ## Formatting
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 By default, Wikked will use [Markdown][] syntax, so that things like these:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 Ring around the rosie, a pocket full of *spears*! Thought you were pretty
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11 foxy, didn't you? **Well!** The last to go will see the first three go
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12 before her! _And your mangy little dog, too!_
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14 ...turn into this:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
16 > Ring around the rosie, a pocket full of *spears*! Thought you were pretty
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17 > foxy, didn't you? **Well!** The last to go will see the first three go
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 > before her! _And your mangy little dog, too!_
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20 [markdown]: http://daringfireball.net/projects/markdown/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
22 Page files that have a `.md` extension will be formatted using Markdown. Other
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23 formats can be used, like Textile, by using other extensions.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26 ## Links
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28 Wikked uses a simple wiki link syntax:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30 * Links are made with double square brackets: `[[Flying monkeys]]` will link to a
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31 page called `Flying monkeys.md`.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 * Linking respects the "current directory", _i.e._ the directory of the current
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 page. Linking to `Flying monkeys` from `Villains/Wicked Witch` will lead
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
35 you to `Villains/Flying monkeys`.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37 * To link using an "absolute" path, start with a slash: `[[/Villains/Flying
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38 monkeys]]` will work regardless of the page you're currently writing it into.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 This is for instance useful for templates.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
41 * To link to a page in the parent directory, use `..` like so:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42 `[[../Munchkins]]`.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44 * You can quickly link to "child" pages by using `./`. For example, if you have
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45 a page called `/Munchkins` that links to `[[./Lollipop Guild]]`, it will lead
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46 to the page `/Munchkins/Lollipop Guild`.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
47
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48 * To give a different display name, write it before a vertical bar: `[[click
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49 here|Flying monkeys]]`.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 ## Metadata
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54 To assign metadata to a page, use `{%raw%}{{name: value}}{%endraw%}`. For instance:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
56 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
57 {{category: Witches}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
58 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
59
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60 You may need to assign a long value, like the summary of the page, which you may
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61 not want to write all in one single line. In that case, you can use multiple
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62 lines, but you need to put the closing double curly braces by themselves on the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
63 last line:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
65 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66 {{summary: This page is about flying monkeys, who serve
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
67 the wicked witch of the west. They're not very bright
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
68 but they are extremely loyal.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
69 }}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72 > Note that the carriage return to get to the closing braces won't be included
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
73 > in the metadata. If you want the metadata value to end with a carriage return,
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
74 > you'll need to add one, effectively leaving an empty line before the closing
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
75 > braces.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
76
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77 Finally, you can also set a metadata without any value if the point is just to
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78 metaphorically flip a switch on the page. Just leave the value empty:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
80 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
81 {{is_villain: }}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
82 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
83
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
84
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
85 ### Well-know metadata
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
86
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
87 Although most metadata you'll use will be for you only, some of it is used to
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
88 tell Wikked to do something special.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
89
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
90 * `category`: Adds the current page to the given category. You can specify this
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
91 metadata multiple times to make the page part of multiple categories. The
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
92 Wikked UI will show the categories of a page at the bottom.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
93
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
94 * `notitle`: If specified, the Wikked UI won't show the title of this page. This
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
95 lets you use a banner graphic or some other way to present the page to
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
96 a visitor.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
97
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
98 * `redirect`: Redirects to another page.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
99
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
100 * `readers`: Specifies the users who can read this page. When not present, the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
101 default readers for the wiki will be able to read the page. See the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
102 [configuration page][1] for more information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
103
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
104 * `writers`: Similar to the previous metadata, but for the ability to edit
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
105 a page.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
106
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
107
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
108
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
109 ## Includes
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
110
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
111 The metadata syntax is also used for including and querying pages. For instance,
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
112 to include the `Warning` page in another page:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
113
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
114 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
115 {{include: Warning}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
116 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
117
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
118 You can supply a relative or absolute page name to the `include` meta. For
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
119 convenience, however, Wikked will first look in the `/Templates` folder for a
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
120 page of that name to include. If it doesn't find one, it will resolve the path
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
121 as usual.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
122
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
123 > You can make Wikked look into a different folder than `/Templates` by changing
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
124 > the `templates_dir` option in the configuration file. See the [configuration
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
125 > documentation][1] for more information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
126
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
127 The `include` metadata accepts arguments. For example, the `City of Oz`
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
128 page may have this at the top:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
129
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
130 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
131 {{include: Warning
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
132 |a work in progress
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
133 |adding references
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
134 }}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
135 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
136
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
137 Those arguments can then be used by the included `/Templates/Warning` page:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
138
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
139 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
140 WARNING! This page is {{__args[0]}}.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
141 You can help by {{__args[1]}}.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
142 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
143
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
144 This will make `City of Oz` print the following warning:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
145
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
146 WARNING! This page is a work in progress.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
147 You can help by adding references.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
148
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
149 As you can see, arguments are passed as an array named `__args`, and this can be
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
150 inserted using double curly brackets. So {%raw%}`{{__args[0]}}`{%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
151 inserts the first passed argument, {%raw%}`{{__args[1]}}`{%endraw%} inserts the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
152 second, and so on.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
153
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
154 You can also pass arguments by name:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
155
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
156 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
157 {{include: Presentation
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
158 |what=dog
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
159 |nickname=Toto
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
160 }}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
161 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
162
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
163 And use them by name in the included template:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
164
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
165 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
166 My {{what}} is called {{nickname}}.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
167 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
168
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
169 In reality, when included, a page's text will be processed through [Jinja2][]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
170 templating so you can also use all kinds of fancy logic. For example, if you
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
171 want to support a default warning message, and an optional information message,
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
172 you can rewrite the `/Template/Warning` page like so:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
173
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
174 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
175 WARNING! This page is {{__args[0]|default('not ready')}}.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
176 {%if __args[1]%}You can help by {{__args[1]}}.{%endif%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
177 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
178
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
179 For more information about what you can do, refer to the [Jinja2 templating
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
180 documentation][jinja2_tpl].
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
181
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
182 [jinja2]: http://jinja.pocoo.org/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
183 [jinja2_tpl]: http://jinja.pocoo.org/docs/templates/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
184
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
185 Pages with other pages included in them inherit the meta properties of the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
186 included pages. You can tweak that behaviour:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
187
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
188 * Meta properties that start with `__` (double underscore) will be "local" or
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
189 "private" to that page, _i.e._ they won't be inherited by pages including the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
190 current one.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
191 * Meta properties that start with `+` (plus sign) will only be "added" or
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
192 "given" to pages including the current one, _i.e._ the current page won't have
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
193 that property, but pages including it will.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
194
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
195
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
196 ## Queries
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
197
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
198 The query metadata takes the name and value of another metadata to query on
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
199 pages. So for instance you can display a list of pages in the "_Witches_"
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
200 category like so:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
201
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
202 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
203 {{query: category=Witches}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
204 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
205
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
206 This will print a bullet list of the matching pages' titles, with a link to
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
207 each.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
208
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
209 You can customize how the list looks like by setting the following arguments:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
210
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
211 * `__header`: The text to print before the list. The default is an empty line.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
212 * `__item`: The text to print for each matching page. It defaults to: `*
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
213 {%raw%}[[{{title}}|{{url}}]]{%endraw%}` (which means, as per Markdown
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
214 formatting, that it will print a bulleted list of titles linking to each
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
215 page).
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
216 * `__footer`: The text to print after the list. The default is an empty line.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
217 * `__empty`: The text to show when no pages match the query. It defaults to a
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
218 simple text saying that no page matched the query.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
219
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
220 So for example, to display a description of each page next to its link, where
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
221 the description is taken from a `description` metadata on each matching page,
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
222 you would do:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
223
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
224 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
225 {{query: category=Witches
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
226 |__item=* [[{{title}}|{{url}}]]: {{description}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
227
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
228 }}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
229 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
230
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
231 Note the extra empty line so that each item has a line return at the end...
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
232 otherwise, they would be all printed on the same line!
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
233
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
234 When a query parameter gets too complicated, you can store it in a separate
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
235 metadata property, as long as that property starts with a double underscore:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
236
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
237 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
238 {{__queryitem: * [[{{title}}|{{url}}]]: {{description}} }}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
239
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
240 {{query: category=Witches|__item=__queryitem}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
241 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
242
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
243 For extra long item templates, you can use a dedicated page. For example, here's
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
244 how you use the text in `/Templates/Witches Item` as the query item template:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
245
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
246 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
247 {{query: category=Witches|__item=[[/Templates/Witches Item]]}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
248 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
249
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
250
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
251 [1]: {{pcurl('configuration')}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
252