Loading...

All project content is available for reading, but you need to be a member of the project for Subversion checkout of source code, or to create/modify any information.
Login if you are a member. Apply here to request membership (open to all).

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 {{{ }}} makes monospace => `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:

.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.
 1. Another number - note that the actual number value does not matter.
   1. 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.
    1. 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:

VariableUse
iCounter for 'for' loops.
nNumber 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 The Front Page of the Project or 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.