Mercurial > wikked

comparison docs/pages/04_syntax.md @ 382:3a61f45702cb

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