Wiki Markup Tutorial

TOC(depth=2) = Learn Basic Wiki Text Markup in 5 Minutes! =

Wiki text is a simple text-based markup language. It takes what is basically plain text input, and it gets converted to HTML output. This quick introduction will teach you the basics of writing text that gives you the output you need - with pointers to more information.

The wiki markup can be used more or less anywhere on CodeResort - wiki pages, tickets and ticket comments, forum, Subversion commit log messages and so on. Anywhere editable.

== First minute: Just write text ==

Plain text uses empty lines to separate parapgraphs. So just writing text as you normally would makes the output you expect:

{{{ This is just some plain text. It will get formatted automatically.

This is more text that will appear in a new paragraph. But this will be the same paragraph. }}}

''Result:''

This is just some plain text. It will get formatted automatically.

This is more text that will appear in a new paragraph. But this will be the same paragraph.

== Second minute: Basic formatting ==

Wiki formatting uses some special markers to denote certain styles of output. Here is a simple set of rules for basics:

• 3 x '-ticks before and after => '''bold''' ('''bold''')
• 2 x '-ticks before and after => ''italic'' (''italic'')
• 2 x _-underscores before and after => underline (__underline__)
• 1 x {{{}}}-backtick or wrapping in 3 x curly brackets {{{ }}}makesmonospace => {{{monospace}}} or {{{monospace}}}`

When pasting monospace lines - typically from logs, source files and so on, make the {{{ }}} section span muliple lines:

{{{ {{{ This is monospace.

And more. It gets output exactly like it is input - without formatting }}} }}}

''Result:''

{{{ This is monospace.

And more. It gets output exactly like it is input - without formatting }}}

''More information:'' HelpUser/WikiFormatting

If you want to apply syntax highlighting to multi-line text - typically source code - you can also apply a highlighting directive. In general the directive is a mimetype - like text/xml - but most types also support the shorter version (like #!xml):

{{{ {{{ #!text/css .code-block span { font-family: monospace; } }}} }}}

''Result:''

{{{ #!html

.code-block span {
 font-family: monospace;
}

}}}

''More information:'' HelpUser/SyntaxHighlighting

== Third minute: Add structure ==

Structuring text on pages is usually in three forms: Using headings for sections, using various kinds of lists to list items, or putting things inside a table.

Headings are made by wrapping text on a line in =, using count of equal signs to specify the level of the heading.

{{{ ==== This will be a heading 4 (<h4> html tag) ==== }}}

''Result:''

==== This will be a heading 4 (<h4> html tag) ====

Lists follow this simple scheme: Indent text with one space, then use * for unordered lists and 1. for ordered lists. 2 more spaces will indent the list further for next item. Lists end with an empty line marking transition back to regular text.

{{{ Undordered list example:

• Note one empty space before the bullet
  • This will be one level below

Ordered list example:

1. Again, one empty space first.
2. Another number - note that the actual number value does not matter.
3. And again at one level lower. }}}

''Result:'''

Undordered list example:

• Note one empty space before the bullet
  • This will be one level below

Ordered list example:

1. Again, one empty space first.
2. Another number - note that the actual number value does not matter.
3. And again at one level lower.

One last thing, same indenting can be used to make block quotes - just start the paragraph with one empty space:

{{{ This is my blockquote. Again start with empty space(s). }}}

''Result:''

This is my blockquote. Again start with empty space(s).

Tables use two || vertical lines to mark borders on the side of the cells. Open and close cells, and put content inside:

{{{ ||''Variable''||''Use''|| ||i||Counter for 'for' loops.|| ||n||Number of items.|| }}}

''Result:''

||''Variable''||''Use''|| ||i||Counter for 'for' loops.|| ||n||Number of items.||

''More information:'' HelpUser/WikiFormatting

== Fourth Minute: Linking ==

The real value of CodeResort comes with linking information, and more or less any resource can be linked to using an explicit syntax of realm:id:

{{{ wiki:WikiStart ticket:23 changeset:44 log:/trunk source:/trunk/README.txt search:MyComponent milestone:1.0 query:status!=closed attachment:MyFile.doc (or if on some other page then attachment:WikiStart:MyFile.doc }}}

As this help page renders outside project context, the links won't display correctly. Instead try similar links, for instance on a wiki:SandBox wiki page in your project that you can use to test out the syntax.

Once you get more familiar with linking, most of these also have shortcut versions, allowing you to use #23 for tickets, [44] for changesets and similar. Wiki page names using !CamelCase naming will be linked automatically.

A variation of internal linking is using the project-relative link syntax, starting with / - like [/newticket Create New Ticket] and [/wiki wiki]. This will work for any URL inside the project.

External links are also fully supported, so just writing http://www.coderesort.com will make it into a link automagically: http://www.coderesort.com.

If you don't want the link to display, but instead want to use your own label, then wrap the link in brackets. Anything after link but before closing bracket become the label:

{{{ '''Example only:''' See [wiki:WikiStart The Front Page of the Project] or [http://www.coderesort.com CodeResort]. }}}

''Result:''

'''Example only:''' See [wiki:WikiStart The Front Page of the Project] or [http://www.coderesort.com CodeResort].

Links can be escaped. If you want to write something that isn't a link, but that normally renders like a link, prefix it with a '!' - so that !http://www.coderesort.com becomes !http://www.coderesort.com. It works for any type of link - !#1 becomes just regular text: !#1.

''More information:'' HelpUser/Links (full listing of supported link types, including some advanced topics)

== Fifth Minute: Embedding special items ==

Not all things are easily done as plain text only, so there is support for some additional features - commonly known as Macros. They basically contains some pre-made rules for transforming input into output.

One common macro is the Image macro. It allows you to embed images inside wiki content. The input for the Image macro is the reference of an image file, and it also supports some means of styling - floating it to the side of the page for instance. General usage:

1. Attach the file to the ticket or wiki page where you want to use it.
2. Use the [[Image(myimage.png)]] text at the point in the text where you want the image to appear.

The [[ ]] is the general macro syntax, and a number of macros are available. Generally they are used to insert dynamic content.

''More information:'' HelpUser/WikiMacros

The {{{ }}} we used above also had an example of #!xml declaration to specify syntax hightlighting for XML source. This is actually a processor that takes input and transforms it to some HTML markup for its special needs.

In addition to the syntax-hightlighting processors there are two very handy processors that basically allows you to wrap some content in a <div> or <span>, both supporting some basic arguments typically for styling the output.

''More information:'' HelpUser/WikiAdvanced (including examples)

== Finished - Try it yourself! ==

The simple tutorial above should give you the tools you need to write what you want - and make it easy to read for others. Learn the simple mechanisms, and then just continue to use it. It will soon become a very natural way of expressing your thoughts and ideas to others.

Note that in a number of places, the wiki textarea also supports a WYSIWYG editor. Now that you've worked your way through the basic understanding of the wiki markup, using a user-friendly editor will also both be safer and make more sense - you'll know what to input when it asks for links, and you'll know how to switch between the modes to reorganize and fine-tune appearances.

Use the Help section and look up the specifics when you are unsure - and remember to use Preview when editing to make sure you get the intended output.