====== Formatting Syntax ======
[[http://wiki.splitbrain.org/wiki:dokuwiki|Dokuwiki]] supports some simple markup language, which tries to make the datafiles to be as readable as possible. This page contains all most 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 bottom of the page. If you want to try something, just use the [[usage:sandbox:overview|sandbox]] page. The simpler markup is easily accessible via [[usage:syntax#quickbuttons|quickbuttons]], too.
===== Quickbuttons =====
The Editing-Toolbar is based upon the one from [[wpmeta>MediaWiki]]. It becomes visible above the editbox automatically if your Browser is capable of the **//needed//** JavaScript. They work pretty much like the formatting buttons in your favourite word processor. In Mozilla and IE you can select a word and press a button to format theselected word. If you **click without** a //selection//, it inserts sample text at the cursor.
Browsers without support to insert at the current cursor position will add the string to the end of the edit box.
Most buttons have accesskeys assigned to them, too.
^ Button ^ Key ^ Function ^
| {{http://wiki.splitbrain.org/lib/images/toolbar/bold.png?nolink}} | ''**b**'' | bold formatting |
| {{http://wiki.splitbrain.org/lib/images/toolbar/italic.png?nolink}} | ''**i**'' | italic formatting |
| {{http://wiki.splitbrain.org/lib/images/toolbar/underline.png?nolink}} | ''**u**'' | underlined formatting |
| {{http://wiki.splitbrain.org/lib/images/toolbar/strike.png?nolink}} | ''**d**'' | strikethrough formatting |
| {{http://wiki.splitbrain.org/lib/images/toolbar/h1.png?nolink}} | ''**1**'' | size 1 headline |
| {{http://wiki.splitbrain.org/lib/images/toolbar/h2.png?nolink}} | ''**2**'' | size 2 headline |
| {{http://wiki.splitbrain.org/lib/images/toolbar/h3.png?nolink}} | ''**3**'' | size 3 headline |
| {{http://wiki.splitbrain.org/lib/images/toolbar/h4.png?nolink}} | ''**4**'' | size 4 headline |
| {{http://wiki.splitbrain.org/lib/images/toolbar/h5.png?nolink}} | ''**5**'' | size 5 headline |
| {{http://wiki.splitbrain.org/lib/images/toolbar/link.png?nolink}} | ''**l**'' | link formatting |
| {{http://wiki.splitbrain.org/lib/images/toolbar/linkextern.png?nolink}} | | external link formatting |
| {{http://wiki.splitbrain.org/lib/images/toolbar/ol.png?nolink}} | | ordered list item |
| {{http://wiki.splitbrain.org/lib/images/toolbar/ul.png?nolink}} | | unordered list item |
| {{http://wiki.splitbrain.org/lib/images/toolbar/hr.png?nolink}} | | horizontal rule |
| {{http://wiki.splitbrain.org/lib/images/toolbar/image.png?nolink}} | | Media Selection |
| {{http://wiki.splitbrain.org/lib/images/toolbar/smiley.png?nolink}} | | smiley picker |
| {{http://wiki.splitbrain.org/lib/images/toolbar/chars.png?nolink}} | | character picker |
| {{http://wiki.splitbrain.org/lib/images/toolbar/sig.png?nolink}} | ''**y**'' | signature (only when logged in)|
===== Basic text formatting =====
DokuWiki supports **bold**, //italic//, __underlined__ and ''monospaced'' texts. Of course you can **__//''combine''//__** all these.
DokuWiki supports **bold**, //italic//, __underlined__ and ''monospaced'' texts.
Of course you can **__//''combine''//__** all these.
You can also colourise your text.
You can also colourise your text.
Following colours are available:
* black
* navy
* blue
* green
* teal
* aqua
* maroon
* purple
* olive
* gray
* silver
* red
* fuchsia
* yellow
* white (white)
* orange
You can use subscript and superscript, too.
You can use subscript and superscript, too.
You can mark something as deleted as well.
You can mark something as deleted as well.
**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.
This is some text with some linebreaks\\ Note that the
two backslashes are only recognized at the end of a line\\
or followed by\\ a whitespace \\this happens without it.
This is some text with some linebreaks\\ Note that the
two backslashes are only recognized at the end of a line\\
or followed by\\ a whitespace \\this happens without it.
You should use forced newlines only if really needed.
===== Links =====
DokuWiki supports multiple ways of creating links.
==== External ====
External links are recognized automagically: http://www-bd.gsi.de or simply www-bd.gsi.de - You can set Linknames, too: [[http://www-bd.gsi.com|This Link points to our department page]]. Email addresses like this one: are recognized, too.
External links are recognized automagically: http://www-bd.gsi.de or simply www-bd.gsi.de -
You can set Linknames, too: [[http://www-bd.gsi.com|This Link points to our department page]].
Email addresses like this one: are recognized, too.
==== Internal ====
Internal links are created by using square brackets. You can either just give a [[pagename]] or use an additional [[pagename|Title Text]]. Wiki pagenames are converted to lowercase automatically, special characters are not allowed.
Internal links are created by using square brackets. You can either just give
a [[usage:pagename]] or use an additional [[usage:pagename|Title Text]]. Wiki pagenames
are converted to lowercase automatically, special chars are not allowed.
You can use [[usage:namespaces]] by using a colon in the pagename.
You can use [[usage:namespaces]] by using a colon in the pagename.
Linking to a specific section is possible, too. Just add the section name behind a hash character as known from HTML. This links to [[usage:syntax#internal|this Section]].
This links to [[usage:syntax#internal|this Section]].
Links to [[usage:syntax|existing pages]] are shown in a different style from [[usage:nonexisting]] ones.
==== Image Links ====
You 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:
[[http://www.gsi.de|{{usage:gsi_logo.png|}}]]
[[http://www.gsi.de|{{usage:gsi_logo.png|}}]]
Please note: The image formatting is the only formatting syntax accepted in link names.
===== Footnotes =====
You can add footnotes ((This is a footnote)) by using double parentheses.
You can add footnotes ((This is a footnote)) by using double parentheses.
===== Sectioning =====
You 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 ''~~NOTOC~~'' in the document.
==== Headline Level 3 ====
=== Headline Level 4 ===
== Headline Level 5 ==
==== Headline Level 3 ====
=== Headline Level 4 ===
== Headline Level 5 ==
By using four or more dashes, you can make a horizontal line:
----
===== Images and other files =====
You can include external and internal images with curly brackets. Optionally you can specify the size of them.
Real size: {{usage:gsi_logo.png}}
Resize to given width: {{usage:gsi_logo.png?50}}
Resize to given width and height: {{usage:gsi_logo.png?400x50}}
Resized external image: {{http://www-bd-new.gsi.de/dokuwiki/lib/tpl/arctic/images/gsi-sd-logo.png?100}}
Real size: {{usage:gsi_logo.png}}
Resize to given width: {{usage:gsi_logo.png?50}}
Resize to given width and height: {{usage:gsi_logo.png?400x50}}
Resized external image: {{http://www-bd-new.gsi.de/dokuwiki/lib/tpl/arctic/images/gsi-sd-logo.png?50}}
By using left or right whitespaces you can choose the alignment.
{{ usage:gsi_logo.png}}
{{usage:gsi_logo.png }}
{{ usage:gsi_logo.png }}
{{ usage:gsi_logo.png}}
{{usage:gsi_logo.png }}
{{ usage:gsi_logo.png }}
Of course, you can add a title (displayed as a tooltip by most browsers), too.
{{ usage:gsi_logo.png |This is the caption.}}
{{ usage:gsi_logo.png |This is the caption.}}
If you specify a filename (external or internal) that is not an image (''gif, jpeg, png''), then it will be displayed as a link instead.
For linking an image to another page see [[#Image Links]] above.
===== Lists =====
Dokuwiki 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.
* This is a list
* The second item
* You may have different levels
* Another item
- The same list but ordered
- Another item
- Just use indention for deeper levels
- That's it
* This is a list
* The second item
* You may have different levels
* Another item
- The same list but ordered
- Another item
- Just use indention for deeper levels
- That's it
===== Smileys =====
DokuWiki 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.
* 8-) %% 8-) %%
* 8-O %% 8-O %%
* :-( %% :-( %%
* :-) %% :-) %%
* =) %% =) %%
* :-/ %% :-/ %%
* :-\ %% :-\ %%
* :-? %% :-? %%
* :-D %% :-D %%
* :-P %% :-P %%
* :-O %% :-O %%
* :-X %% :-X %%
* :-| %% :-| %%
* ;-) %% ;-) %%
* ^_^ %% ^_^ %%
* :?: %% :?: %%
* :!: %% :!: %%
* LOL %% LOL %%
* FIXME %% FIXME %%
* DELETEME %% DELETEME %%
===== Typography =====
Dokuwiki can convert simple text characters to their typographically correct entities. Here is an example of recognized characters.
-> <- <-> => <= <=> >> << -- --- 640x480 (c) (tm) (r)
"He thought 'It's a man's world'..."
-> <- <-> => <= <=> >> << -- --- 640x480 (c) (tm) (r)
"He thought 'It's a man's world'..."
===== Quoting =====
Some times you want to mark some text to show it's a reply or comment. You can use the following syntax:
I think we should do it
> No we shouldn't
>> Well, I say we should
> Really?
>> Yes!
>>> Then lets do it!
I think we should do it
> No we shouldn't
>> Well, I say we should
> Really?
>> Yes!
>>> Then lets do it!
===== Tables =====
DokuWiki supports a simple syntax to create tables.
^ Heading 1 ^ Heading 2 ^ Heading 3 ^
| Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 |
| Row 2 Col 1 | some colspan (note the double pipe) ||
| Row 3 Col 1 | Row 2 Col 2 | Row 2 Col 3 |
Table rows have to start and end with a ''|'' for normal rows or a ''^'' for headers.
^ Heading 1 ^ Heading 2 ^ Heading 3 ^
| Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 |
| Row 2 Col 1 | some colspan (note the double pipe) ||
| Row 3 Col 1 | Row 2 Col 2 | Row 2 Col 3 |
To connect cells horizontally, just make the next cell completely empty as shown above. Be sure to have always the same amount of cell separators!
Vertical tableheaders are possible, too.
| ^ Heading 1 ^ Heading 2 ^
^ Heading 3 | Row 1 Col 2 | Row 1 Col 3 |
^ Heading 4 | no colspan this time | |
^ Heading 5 | Row 2 Col 2 | Row 2 Col 3 |
As you can see, it's the cell separator before a cell which decides about the formatting:
| ^ Heading 1 ^ Heading 2 ^
^ Heading 3 | Row 1 Col 2 | Row 1 Col 3 |
^ Heading 4 | no colspan this time | |
^ Heading 5 | Row 2 Col 2 | Row 2 Col 3 |
Note: Vertical spans (rowspan) are not possible.
You 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.
^ Table with alignment ^^^
| right| center |left |
|left | right| center |
| xxxxxxxxxxxx | xxxxxxxxxxxx | xxxxxxxxxxxx |
This is how it looks in the source:
^ Table with alignment ^^^
| right| center |left |
|left | right| center |
| xxxxxxxxxxxx | xxxxxxxxxxxx | xxxxxxxxxxxx |
===== Non-parsed Blocks =====
You 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''.
This is preformatted code all spaces are preserved: like <-this
This is pretty much the same, but you could use it to show that you quoted a file.
To 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 ''%%''.
This is some text which contains addresses like this: http://www.gsi.de and **formatting**, but nothing is done with it.
See the source of this page to see how to use these blocks.
===== Syntax Highlighting =====
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. ''
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}
The 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//
===== Picture Gallery =====
A basic gallery can be added by selecting a [[namespace]] like this:
{{gallery>namespace}}
All imagefiles in the selected namespace will be added to the image gallery. Note: those images need to be a valid [[pagename]], eg. all lowercase.
Instead of using a whole namespace of images, you can also specify a single image -- this makes most sense when combined with the lightbox mode (see below).
{{gallery>namespace:someimage.jpg}}
The created gallery can be aligned by using whitespace (defaults to centered):
{{gallery> namespace}} (right aligned)
{{gallery>namespace }} (left aligned)
{{gallery> namespace }} (centered)
You can define the wanted thumbnail size by adding its dimension as parameter:
{{gallery>namespace?150x150}}
The default is a dimension of 120x120 pixels.
You can define the number of columns as well:
{{gallery>namespace?6}}
The default number of columns is 5 and can be configured in the config manager. If you specify a 0 no table is used instead all thumbnails are added in a sequence.
To have the filename displayed below the thumbnails add the ''showname'' parameter (if this is made the default in the config, you may disable it with ''noshowname''):
{{gallery>namespace?showname}}
If you want the files sorted in the reverse order use the ''reverse'' keyword (if this is made the default in the config, you may disable it with ''noreverse''):
{{gallery>namespace?reverse}}
If you don't want to link to the image detail pages but directly to the image itself use the ''direct'' parameter (if this is made the default in the config, you may disable it with ''nodirect''):
{{gallery>namespace?direct}}
For fancy JavaScript based inline browsing of the images use the ''lightbox'' keyword ((This feature is based on the [[http://www.huddletogether.com/projects/lightbox/|Lightbox]] and [[http://serennz.cool.ne.jp/sb/sp/lightbox/|Lightbox Plus]] scripts with some additions)). This feature implicitly sets the direct parameter. If this is made the default in the config, you may disable it with ''nolightbox''.
{{gallery>namespace?lightbox}}
All params can be combined:
{{gallery>namespace?150x150&6&showname}}
You can also specify the size of lightbox images. It is done the same way as with thumbnails, except using a capital 'X'. The default is 800X600.
{{gallery>namespace?lightbox&500X400}}
IMPORTANT: When you have added your pictures they may not show up in the gallery: add '&purge=true' to the end of the URL to clear the cache - and then you should see them.
=== About the Lightbox mode ===
This mode will open the clicked picture inside the current browser window without leaving the current page. You can close the picture view by clicking the little X in the upper right corner or anywhere in the picture. You can move to the next or previous image by using the arrow buttons in the lower corners.
The picture is downsized if necessary to fit into the current browser window. You can enlarge it with the arrow button in the top corner.
The following keys can be used to navigate:
^ Key ^ Action ^
| ''->'' or ''n'' | next image |
| ''<-'' or ''p'' | previous image |
| ''x'' or ''c'' or ''ESC'' | close the image view |
The Lightbox feature will also be used for all images embedded using the standard DokuWiki image syntax and having set the ''direct'' parameter. This behavior can easily be disabled by changing the ''lightboxForEveryImg'' variable to ''0'' at the very top of the ''script.js'' file.
More info at :[[http://www.dokuwiki.org/plugin:gallery|DokuWiki-Gallery]]
Note: The feature does not use [[http://www.huddletogether.com/projects/lightbox2/|Version 2]] of the Lightbox script because of its heavy and DokuWiki-incompatible dependencies.