1====== Formatting Syntax ======
2
3[[wiki:DokuWiki]] supports some simple markup language, which tries to make the datafiles to be as readable as possible. This page contains all possible syntax you may use when editing the pages. Simply have a look at the source of this page by pressing the //Edit this page// button at the top or bottom of the page. If you want to try something, just use the [[playground:playground|playground]] page. The simpler markup is easily accessible via [[doku>wiki:quickbuttons|quickbuttons]], too.
4
5===== Basic text formatting =====
6
7DokuWiki supports **bold**, //italic//, __underlined__ and ''monospaced'' texts. Of course you can **__//''combine''//__** all these.
8
9  DokuWiki supports **bold**, //italic//, __underlined__ and ''monospaced'' texts.
10  Of course you can **__//''combine''//__** all these.
11
12You can use <sub>subscript</sub> and <sup>superscript</sup>, too.
13
14  You can use <sub>subscript</sub> and <sup>superscript</sup>, too.
15
16You can mark something as <del>deleted</del> as well.
17
18  You can mark something as <del>deleted</del> as well.
19
20**Paragraphs** are created from blank lines. If you want to **force a newline** without a paragraph, you can use two backslashes followed by a whitespace or the end of line.
21
22This is some text with some linebreaks\\ Note that the
23two backslashes are only recognized at the end of a line\\
24or followed by\\ a whitespace \\this happens without it.
25
26  This is some text with some linebreaks\\ Note that the
27  two backslashes are only recognized at the end of a line\\
28  or followed by\\ a whitespace \\this happens without it.
29
30You should use forced newlines only if really needed.
31
32===== Links =====
33
34DokuWiki supports multiple ways of creating links.
35
36==== External ====
37
38External links are recognized automagically: http://www.google.com or simply www.google.com - You can set Linknames, too: [[http://www.google.com|This Link points to google]]. Email addresses like this one: <andi@splitbrain.org> are recognized, too.
39
40  DokuWiki supports multiple ways of creating links. External links are recognized
41  automagically: http://www.google.com or simply www.google.com - You can set
42  Linknames, too: [[http://www.google.com|This Link points to google]]. Email
43  addresses like this one: <andi@splitbrain.org> are recognized, too.
44
45==== Internal ====
46
47Internal links are created by using square brackets. You can either just give a [[doku>wiki:pagename]] or use an additional [[doku>wiki:pagename|Title Text]]. Wiki pagenames are converted to lowercase automatically, special characters are not allowed.
48
49  Internal links are created by using square brackets. You can either just give
50  a [[pagename]] or use an additional [[pagename|Title Text]]. Wiki pagenames
51  are converted to lowercase automatically, special chars are not allowed.
52
53You can use [[wiki:namespaces]] by using a colon in the pagename.
54
55  You can use [[wiki:namespaces]] by using a colon in the pagename.
56
57For details about namespaces see [[doku>wiki:namespaces]].
58
59Linking to a specific section is possible, too. Just add the section name behind a hash character as known from HTML. This links to [[syntax#internal|this Section]].
60
61  This links to [[syntax#internal|this Section]].
62
63Notes:
64
65  * Links to [[wiki:syntax|existing pages]] are shown in a different style from [[wiki:nonexisting]] ones.
66  * DokuWiki does not use [[wp>CamelCase]] to automatically create links by default, but this behaviour can be enabled in the [[doku>wiki:config]] file. Hint: If DokuWiki is a link, then it's enabled.
67  * When a section's heading is changed, its bookmark changes, too. So don't rely on section linking too much.
68
69==== Interwiki ====
70
71DokuWiki supports [[doku>wiki:interwiki|Interwiki]] links. These are quick links to other Wikis. For example this is a link to Wikipedia's page about Wikis: [[wp>Wiki]].
72
73  DokuWiki supports [[doku>wiki:interwiki|Interwiki]] links. These are quick links to other Wikis.
74  For example this is a link to Wikipedia's page about Wikis: [[wp>Wiki]].
75
76
77==== Windows Shares ====
78
79Windows shares like [[\\server\share|this]] are recognized, too. Please note that these only make sense in a homogenous user group like a corporate [[wp>Intranet]].
80
81  Windows Shares like [[\\server\share|this]] are recognized, too.
82
83Notes:
84
85  * For security reasons direct browsing of windows shares only works in Microsoft Internet Explorer per default (and only in the "local zone").
86  * For Mozilla and Firefox it can be enabled through the config option [[http://www.mozilla.org/quality/networking/docs/netprefs.html#file|security.checkloaduri]] but this is not recommended.
87  * See [[dokubug>151]] for more info.
88
89==== Image Links ====
90
91You can also use an image to link to another internal or external page by combining the syntax for links and [[#images_and_other_files|images]] (see below) like this:
92
93  [[http://www.php.net|{{wiki:dokuwiki-128.png}}]]
94
95[[http://www.php.net|{{wiki:dokuwiki-128.png}}]]
96
97Please note: The image formatting is the only formatting syntax accepted in link names.
98
99The whole [[#images_and_other_files|image]] and [[#links|link]] syntax is supported (including image resizing, internal and external images and URLs and interwiki links).
100
101===== Footnotes =====
102
103You can add footnotes ((This is a footnote)) by using double parentheses.
104
105  You can add footnotes ((This is a footnote)) by using double parentheses.
106
107===== Sectioning =====
108
109You can use up to five different levels of headlines to structure your content. If you have more than three headlines, a table of contents is generated automatically -- this can be disabled by including the string ''<nowiki>~~NOTOC~~</nowiki>'' in the document.
110
111==== Headline Level 3 ====
112=== Headline Level 4 ===
113== Headline Level 5 ==
114
115  ==== Headline Level 3 ====
116  === Headline Level 4 ===
117  == Headline Level 5 ==
118
119By using four or more dashes, you can make a horizontal line:
120
121----
122
123===== Images and other files =====
124
125You can include external and internal [[doku>wiki:images]] with curly brackets. Optionally you can specify the size of them.
126
127Real size:                        {{wiki:dokuwiki-128.png}}
128
129Resize to given width:            {{wiki:dokuwiki-128.png?50}}
130
131Resize to given width and height: {{wiki:dokuwiki-128.png?200x50}}
132
133Resized external image:           {{http://de3.php.net/images/php.gif?200x50}}
134
135  Real size:                        {{wiki:dokuwiki-128.png}}
136  Resize to given width:            {{wiki:dokuwiki-128.png?50}}
137  Resize to given width and height: {{wiki:dokuwiki-128.png?200x50}}
138  Resized external image:           {{http://de3.php.net/images/php.gif?200x50}}
139
140
141By using left or right whitespaces you can choose the alignment.
142
143{{ wiki:dokuwiki-128.png}}
144
145{{wiki:dokuwiki-128.png }}
146
147{{ wiki:dokuwiki-128.png }}
148
149  {{ wiki:dokuwiki-128.png}}
150  {{wiki:dokuwiki-128.png }}
151  {{ wiki:dokuwiki-128.png }}
152
153Of course, you can add a title (displayed as a tooltip by most browsers), too.
154
155{{ wiki:dokuwiki-128.png |This is the caption}}
156
157  {{ wiki:dokuwiki-128.png |This is the caption}}
158
159If you specify a filename (external or internal) that is not an image (''gif, jpeg, png''), then it will be displayed as a link instead.
160
161For linking an image to another page see [[#Image Links]] above.
162
163===== Lists =====
164
165Dokuwiki supports ordered and unordered lists. To create a list item, indent your text by two spaces and use a ''*'' for unordered lists or a ''-'' for ordered ones.
166
167  * This is a list
168  * The second item
169    * You may have different levels
170  * Another item
171
172  - The same list but ordered
173  - Another item
174    - Just use indention for deeper levels
175  - That's it
176
177<code>
178  * This is a list
179  * The second item
180    * You may have different levels
181  * Another item
182
183  - The same list but ordered
184  - Another item
185    - Just use indention for deeper levels
186  - That's it
187</code>
188
189===== Smileys =====
190
191DokuWiki converts commonly used [[wp>emoticon]]s to their graphical equivalents. More smileys can be placed in the ''smiley'' directory and configured in the ''conf/smileys.conf'' file. Here is an overview of Smileys included in DokuWiki.
192
193  * 8-) %%  8-)  %%
194  * 8-O %%  8-O  %%
195  * :-( %%  :-(  %%
196  * :-) %%  :-)  %%
197  * =)  %%  =)   %%
198  * :-/ %%  :-/  %%
199  * :-\ %%  :-\  %%
200  * :-? %%  :-?  %%
201  * :-D %%  :-D  %%
202  * :-P %%  :-P  %%
203  * :-O %%  :-O  %%
204  * :-X %%  :-X  %%
205  * :-| %%  :-|  %%
206  * ;-) %%  ;-)  %%
207  * ^_^ %%  ^_^  %%
208  * :?: %%  :?:  %%
209  * :!: %%  :!:  %%
210  * LOL %%  LOL  %%
211  * FIXME %%  FIXME %%
212  * DELETEME %% DELETEME %%
213
214===== Typography =====
215
216[[DokuWiki]] can convert simple text characters to their typographically correct entities. Here is an example of recognized characters.
217
218-> <- <-> => <= <=> >> << -- --- 640x480 (c) (tm) (r)
219"He thought 'It's a man's world'..."
220
221<code>
222-> <- <-> => <= <=> >> << -- --- 640x480 (c) (tm) (r)
223"He thought 'It's a man's world'..."
224</code>
225
226Please note: These conversions can be turned off through a [[doku>wiki:config#typography|config option]] and a [[doku>wiki:entities|pattern file]].
227
228===== Quoting =====
229
230Some times you want to mark some text to show it's a reply or comment. You can use the following syntax:
231
232  I think we should do it
233
234  > No we shouldn't
235
236  >> Well, I say we should
237
238  > Really?
239
240  >> Yes!
241
242  >>> Then lets do it!
243
244I think we should do it
245
246> No we shouldn't
247
248>> Well, I say we should
249
250> Really?
251
252>> Yes!
253
254>>> Then lets do it!
255
256===== Tables =====
257
258DokuWiki supports a simple syntax to create tables.
259
260^ Heading 1      ^ Heading 2       ^ Heading 3          ^
261| Row 1 Col 1    | Row 1 Col 2     | Row 1 Col 3        |
262| Row 2 Col 1    | some colspan (note the double pipe) ||
263| Row 3 Col 1    | Row 2 Col 2     | Row 2 Col 3        |
264
265Table rows have to start and end with a ''|'' for normal rows or a ''^'' for headers.
266
267  ^ Heading 1      ^ Heading 2       ^ Heading 3          ^
268  | Row 1 Col 1    | Row 1 Col 2     | Row 1 Col 3        |
269  | Row 2 Col 1    | some colspan (note the double pipe) ||
270  | Row 3 Col 1    | Row 2 Col 2     | Row 2 Col 3        |
271
272To connect cells horizontally, just make the next cell completely empty as shown above. Be sure to have always the same amount of cell separators!
273
274Vertical tableheaders are possible, too.
275
276|              ^ Heading 1            ^ Heading 2          ^
277^ Heading 3    | Row 1 Col 2          | Row 1 Col 3        |
278^ Heading 4    | no colspan this time |                    |
279^ Heading 5    | Row 2 Col 2          | Row 2 Col 3        |
280
281As you can see, it's the cell separator before a cell which decides about the formatting:
282
283  |              ^ Heading 1            ^ Heading 2          ^
284  ^ Heading 3    | Row 1 Col 2          | Row 1 Col 3        |
285  ^ Heading 4    | no colspan this time |                    |
286  ^ Heading 5    | Row 2 Col 2          | Row 2 Col 3        |
287
288Note: Vertical spans (rowspan) are not possible.
289
290You can align the table contents, too. Just add at least two whitespaces at the opposite end of your text: Add two spaces on the left to align right, two spaces on the right to align left and two spaces at least at both ends for centered text.
291
292^           Table with alignment           ^^^
293|         right|    center    |left          |
294|left          |         right|    center    |
295| xxxxxxxxxxxx | xxxxxxxxxxxx | xxxxxxxxxxxx |
296
297This is how it looks in the source:
298
299  ^           Table with alignment           ^^^
300  |         right|    center    |left          |
301  |left          |         right|    center    |
302  | xxxxxxxxxxxx | xxxxxxxxxxxx | xxxxxxxxxxxx |
303
304===== Non-parsed Blocks =====
305
306You can include non-parsed blocks into your documents by either indenting them by at least two spaces (like used for the previous examples) or by using the tags ''code'' or ''file''.
307
308<code>
309This is preformatted code all spaces are preserved: like              <-this
310</code>
311
312<file>
313This is pretty much the same, but you could use it to show that you quoted a file.
314</file>
315
316To let the parser ignore an area completely (ie. do no formatting on it), enclose the area either with ''nowiki'' tags or even simpler, with double percent signs ''<nowiki>%%</nowiki>''.
317
318<nowiki>
319This is some text which contains addresses like this: http://www.splitbrain.org and **formatting**, but nothing is done with it.
320</nowiki>
321
322See the source of this page to see how to use these blocks.
323
324===== Syntax Highlighting =====
325
326[[DokuWiki]] can highlight sourcecode, which makes it easier to read. It uses the [[http://qbnz.com/highlighter/|GeSHi]] Generic Syntax Highlighter -- so any language supported by GeSHi is supported. The syntax is the same like in the code block in the previous section, but this time the name of the used language is inserted inside the tag. Eg. ''<nowiki><code java></nowiki>''.
327
328<code java>
329/**
330 * The HelloWorldApp class implements an application that
331 * simply displays "Hello World!" to the standard output.
332 */
333class HelloWorldApp {
334    public static void main(String[] args) {
335        System.out.println("Hello World!"); //Display the string.
336    }
337}
338</code>
339
340The following language strings are currently recognized: //abap actionscript-french, actionscript, ada, apache, applescript, asm, asp, autoit, bash, basic4gl, blitzbasic, bnf, caddcl, cadlisp, cfdg, cfm, c_mac, c, cpp, cpp-qt, csharp, css, delphi, diff, div, dos, dot, d, eiffel, fortran, freebasic, genero, gml, groovy, haskell, html, idl, ini, inno, io, java5, java, javascript, latex, lisp, lua, m68k, matlab, mirc, mpasm, mysql, nsis, objc, ocaml-brief, ocaml, oobas, oracle8, pascal, perl, per, php-brief, php, plsql, python, qbasic, rails, reg, robots, ruby, sas, scheme, sdlbasic, smalltalk, smarty, sql, tcl, text, thinbasic, tsql, vbnet, vb, vhdl, visualfoxpro, winbatch, xml, xpp, z80//
341
342
343===== RSS/ATOM Feed Aggregation =====
344[[DokuWiki]] can integrate data from external XML feeds. For parsing the XML feeds, [[http://simplepie.org/|SimplePie]] is used. All formats understood by SimplePie can be used in DokuWiki as well. You can influence the rendering by multiple additional space separated parameters:
345
346^ Parameter  ^ Description ^
347| any number | will be used as maximum number items to show, defaults to 8 |
348| reverse    | display the last items in the feed first |
349| author     | show item authors names |
350| date       | show item dates |
351| description| show the item description. If [[doku>wiki:config#htmlok|HTML]] is disabled all tags will be stripped |
352| //n//[dhm] | refresh period, where d=days, h=hours, m=minutes. (e.g. 12h = 12 hours). |
353
354The refresh period defaults to 4 hours. Any value below 10 minutes will be treated as 10 minutes. [[DokuWiki]] will generally try to supply a cached version of a page, obviously this is inappropriate when the page contains dynamic external content. The parameter tells [[DokuWiki]] to re-render the page if it is more than //refresh period// since the page was last rendered.
355
356**Example:**
357
358  {{rss>http://slashdot.org/index.rss 5 author date 1h }}
359
360{{rss>http://slashdot.org/index.rss 5 author date 1h }}
361
362
363===== Embedding HTML and PHP =====
364
365You can embed raw HTML or PHP code into your documents by using the ''html'' or ''php'' tags like this:
366<code>
367<html>
368This is some <span style="color:red;font-size:150%;">inline HTML</span>
369</html>
370<HTML>
371<p style="border:2px dashed red;">And this is some block HTML</p>
372</HTML>
373</code>
374
375<html>
376This is some <span style="color:red;font-size:150%;">inline HTML</span>
377</html>
378<HTML>
379<p style="border:2px dashed red;">And this is some block HTML</p>
380</HTML>
381
382<code>
383<php>
384echo 'A logo generated by PHP:';
385echo '<img src="' . $_SERVER['PHP_SELF'] . '?=' . php_logo_guid() . '" alt="PHP Logo !" />';
386echo '(generated inline HTML)';
387</php>
388<PHP>
389echo '<table class="inline"><tr><td>The same, but inside a block level element:</td>';
390echo '<td><img src="' . $_SERVER['PHP_SELF'] . '?=' . php_logo_guid() . '" alt="PHP Logo !" /></td>';
391echo '</tr></table>';
392</PHP>
393</code>
394
395<php>
396echo 'A logo generated by PHP:';
397echo '<img src="' . $_SERVER['PHP_SELF'] . '?=' . php_logo_guid() . '" alt="PHP Logo !" />';
398echo '(inline HTML)';
399</php>
400<PHP>
401echo '<table class="inline"><tr><td>The same, but inside a block level element:</td>';
402echo '<td><img src="' . $_SERVER['PHP_SELF'] . '?=' . php_logo_guid() . '" alt="PHP Logo !" /></td>';
403echo '</tr></table>';
404</PHP>
405
406**Please Note**: HTML and PHP embedding is disabled by default in the configuration. If disabled, the code is displayed instead of executed.
407
408===== Control Macros =====
409
410Some syntax influences how DokuWiki renders a page without creating any output it self. The following control macros are availble:
411
412^ Macro           ^ Description |
413| %%~~NOTOC~~%%   | If this macro is found on the page, no table of contents will be created |
414| %%~~NOCACHE~~%% | DokuWiki caches all output by default. Sometimes this might not be wanted (eg. when the %%<php>%% syntax above is used), adding this macro will force DokuWiki to rerender a page on every call |
415
416===== Syntax Plugins =====
417
418DokuWiki's syntax can be extended by [[doku>wiki:plugins|Plugins]]. How the installed plugins are used is described on their appropriate description pages. The following syntax plugins are available in this particular DokuWiki installation:
419
420~~INFO:syntaxplugins~~
421