(anonymous guest) (logged out)

Copyright (C) by the contributors. Some rights reserved, license BY-SA.

Sponsored by the Wiki Symposium and the Nuveon GmbH.

 

This is the stable v0.4 spec of Creole (31 Jan 2007). Also see reasoning for more information about individual markup elements.

Changes from Creole 0.3:

  • requirement to support wiki-style linebreaks \\ - (see ChangeLinebreakMarkupProposal)
  • can put line breaks in table cells
  • allow for level one headings like this: = really big heading =

Single element examples#

Bold and Italics#

Bold and Italics should be able to embed in lists and one should be able to make links bold and italic. Bold and/or italics can span lines, but not span across lines in lists nor across different paragraphs.

Bold#

A star (*) is the most used symbol to emphasize text online. Double symbols are generally used in Creole to avoid accidentally parsing text not meant to be parsed. Reasoning

Creole:

 **bold** 

Recommended XHTML:

 <strong>bold</strong> 

Sample Output: bold

Italics#

A slash (/) looks like slanted italics, so it is intuitive and thus easier to remember. Reasoning

Ignore for italics processing if immediately following http: or ftp:

Creole:

 //italics// 

Recommended XHTML:

 <em>italics</em> 

Sample Output: italics


Creole:

Bold and italics should //be
able// to cross lines.

But, should //not be...

...able// to cross paragraphs.

Recommended XHTML:

<p>
Bold and italics should <em>be
able</em> to cross lines.
</p>
<p>
But, should //not be...
</p>
<p>
...able// to cross paragraphs.
</p>

Sample output:

Bold and italics should be
able
to cross lines.

But, should not be...

...able to cross paragraphs.

Bold Italics#

Creole:
**//bold italics//**
//**bold italics**//
//This is **also** good.//

Recommended XHTML:

<strong><em>bold italics</em></strong>
<em><strong>bold italics</strong></em>
<em>This is <strong>also</strong> good.</em>

Sample Output:

Bold italics
Bold italics
This is also good


Unacceptable:

**//bold italics**//
//**bold italics//**

Lists#

Bold, italics, links, pre can be embedded in lists. Whitespace is optional before and after the * or # character, however a space is required afterwards if someone wishes to start a list element with bold text. A list element ends at the end of a line. It is recommended to have support for a depth of at least five levels.

About unordered lists and bold: a line starting with ** (including optional whitespace before and afterwards), immediately following an unordered list element a line above, will be treated as a nested unordered list element. Otherwise it will be treated as the beginning of bold text. Also note that bold and/or italics cannot span lines in a list.

Unordered Lists#

A large majority of wiki engines use an asterisk (*) to denote bullet lists. The multiple asterisk approach for sublists was the first wiki syntax for sublists. Users do not need to count leading spaces like in markups where a sublist level is determined by the number of its leading spaces. Reasoning

Creole:

* Item 1
** Item 1.1
* Item 2

Recommended XHTML:

<ul>
<li>Item 1
  <ul>
  <li>Item 1.1</li>
  </ul>
</li>
<li>Item 2</li>
</ul>

Sample Output:

  • Item 1
    • Item 1.1
  • Item 2

Ordered Lists#

The number sign (#) is used for ordered lists in most wikis. Reasoning

Creole:

# Item 1
## Item 1.1
# Item 2

Recommended XHTML:

<ol>
<li>Item 1
  <ol>
  <li>Item 1.1</li>
  </ol>
</li>
<li>Item 2</li>
</ol>

Sample Output:

  1. Item 1
    1. Item 1.1
  2. Item 2

Headings#

Using equal signs (=) is the most popular wiki header markup. Since there are more equal signs for smaller headers, subheaders will become more indented making it easier to get a visual overview from the markup alone. Closing equal signs are optional, making Creole more flexible since many wiki engines do not require them. Reasoning

Only three different sized levels of headings are required. Closing (right-side) equal signs are optional. If both left side and right side equal signs exist, the left side takes precedence. Whitespace is not allowed before the left-side equal signs. Only whitespace characters are permitted after the closing equal signs. No linebreaks are allowed within headings. Bold, italics, links and preformatted text are not allowed in headings.

Creole:

= Level 1 (largest) =
== Level 2 ==
=== Level 3 ===
==== Level 4 ====
===== Level 5 =====
====== Level 6 ======
=== Also level 3
=== Also level 3 =
=== Also level 3 ==
=== **not** //parsed// ===

Recommended XHTML:

<h1>Level 1 (largest)</h1>
<h2>Level 2</h2>
<h3>Level 3</h3>
<h4>Level 4</h4>
<h5>Level 5</h5>
<h6>Level 6</h6>
<h3>Also level 3</h3>
<h3>Also level 3</h3>
<h3>Also level 3</h3>
<h3>**not** //parsed//</h3>

Links - Internal and External#

Almost all wikis use square brackets ([[]]) to make links. Using double square brackets allows single square brackets to be used freely without worry of turning them into links. Reasoning

Any markup except for images within a link will not be parsed.

Creole:

[[link]]
[[MyBigPage|Go to my page]]
[[http://www.wikicreole.org/]]
http://www.rawlink.org/
[[http://www.wikicreole.org/|Visit the WikiCreole website]]
[[Weird Stuff|**Weird** //Stuff//]]

Recommended XHTML:

<a href="http://www.examplewiki.com/link">link</a>
<a href="http://www.examplewiki.com/MyBigPage">Go to my page</a>
<a href="http://www.wikicreole.org/">http://www.wikicreole.org/</a>
<a href="http://www.rawlink.org/">http://www.rawlink.org/</a>
<a href="http://www.wikicreole.org/">Visit the WikiCreole website</a>
<a href="http://www.examplewiki.com/Weird_Stuff">**Weird** //Stuff//</a>

Sample Output:

link
Go to my page
http://www.wikicreole.org/
http://www.rawlink.org/
Visit the WikiCreole website
__Weird__ ''Stuff''

Paragraphs#

No markup tags should be necessary to start a new paragraph. Reasoning

Blank line makes paragraph.

Creole:

This is my text.

This is more text.

Recommended XHTML:

<p>This is my text.</p>

<p>This is more text.</p>

Sample Output: This is my text.

This is more text.

Line breaks#

blog-style vs. wiki-style
There was a long discussion whether to use blog-style or wiki-style (legacy-style) line breaks. We decided to change the original blog-style line break recommendation (treat linebreaks as line breaks) from Creole 0.3 to the wiki-style linebreaks recommendation. Wikis must support forced line break syntax \\ .

We encourage engine developers that have already implemented the Creole 0.3 style (blog-style) line breaks not to throw away their implementation, but to add an option so that administrators can choose in which mode to run their installation. This way we hope to gain more experience with blog-style line breaks. In a blog-style line break mode, the forced line break syntax must be supported, so that line breaks will properly migrate when people copy text from a wiki with forced line break characters. Reasoning

\\ (wiki-style) for line breaks.

Creole:

This is the first line,\\and this is the second.

Recommended XHTML:

This is the first line,<br />
and this is the second.

Sample Output:

This is the first line,
and this is the second.


Creole:

* This is a single list item
followed by a paragraph?

Recommended XHTML:

<ul>
<li>This is a single list item</li>
</ul>
<p>
followed by a paragraph
</p>

Sample Output:

  • This is a single list item
followed by a paragraph

Preformatted#

There must be a way for users to enter text which will not be formatted by the wiki engine. Triple curly brackets ({{{}}}) were chosen due to their visibility and unlikeliness to be in the "code" itself. Reasoning

This works in-line or as a block. No wiki markup is interpreted between these characters and all characters become monospace. As a block, the three curly braces should be on one line by itself to open and another line of three curly braces should be on a line by itself to close.

Creole:

{{{
//This// does **not** get [[formatted]] 
}}}

Recommended XHTML:

<pre>
//This// does **not** get [[formatted]]
</pre>

Sample Output:

//This// does **not** get [[formatted]]

Creole:

Some examples of markup are: {{{** <i>this</i> ** }}}

Recommended XHTML:

Some examples of markup are: <tt>** <i>this</i> **</tt>

Sample output:

Some examples of markup are: ** <i>this</i> **

Horizontal Rule#

All non-WYSIWYG wikis use hyphens (----) to denote horizontal rules. Most wikis require four. Reasoning

Whitespace is optional before and after the hyphens, but no whitespace is allowed between them. The four hyphens must be the only characters (other than whitespace) on that line.

Creole:

 ---- 
Recommended XHTML:
 <hr /> 

Image (inline)#

The most common image markup was double curly brackets ( {{}} ) which will then have the same internal structure as links for consistency. Reasoning

Creole:

 {{myimage.png|this is my image}} 

Recommended XHTML:

 <img src="myimage.png" alt="this is my image"/> 

Tables#

Most wikis use single or double pipes to separate table cells. Single pipes (|) allow better use of space and are faster to type than double pipes since pipes are not usually needed in table cells. Reasoning

All cells are separated by single pipes. The ending pipe is optional. You can embed links, bold, italics, monospace and line breaks in table cells. Comparison details found on List Of Table Markups

Creole:

|Heading Col 1  |Heading Col 2          |
|Cell 1.1       |Two lines\\in Cell 1.2 |
|Cell 2.1       |Cell 2.2               |

Recommended XHTML:

<table>
<tr>
<td>Heading Col 1</td>
<td>Heading Col 2</td>
</tr>
<tr>
<td>Cell 1.1</td>
<td>Two lines\\in Cell 1.2</td>
</tr>
<tr>
<td>Cell 2.1</td>
<td>Cell 2.2</td>
</tr>
</table>

Sample output:

Heading Col 1 Heading Col 2
Cell 1.1 Two lines
in Cell 1.2
Cell 2.1 Cell 2.2

Placeholder#

This is the only new markup introduced in Creole. Few wikis use angle brackets (<<>>) for markup and it is easy to type on most international keyboards. This was mainly developed due to MediaWiki's extensive use of special characters making it practically impossible to implement Mixed Creole mode. Reasoning

When there is something advanced, a placeholder will show up, so users will not be confused seeing more than one syntax. (optional for wiki developers)

Creole:

 <<x>> 

Mixed syntax examples#

Creole:
//[[Important page|this link is bold]]//
**[[Important page]]**
//**[[Important page]]**//

Recommended XHTML:

<em><a href="http://www.examplewiki.com/Important_Page">this link is bold</a></em>
<strong><a href="http://www.examplewiki.com/Important_page">Important page</a></strong>
<em><strong><a href="http://www.examplewiki.com/Important_page">Important page</a></strong></em>

Sample Output: this link is bold
Important page
Important page

Bold, Italics, Links, Pre in Lists#

Creole:
* **bold** item
* //italic// item
# item about a [[certain page]]
# {{{ //this// is **not** [[processed]] }}}

Recommended XHTML:

<ul>
<li><strong>bold</strong> item</li>
<li><em>italic</em> item</li>
</ul>
<ol>
<li>item about a <a href="http://www.examplewiki.com/certain_page">certain page</a></li>
<li><tt>//this// is **not** [[processed]]</tt></li>
</ol>

Sample Output:

  • bold item
  • italic item
  1. item about a certain page
  2. //this// is **not** [[processed]]

Add new attachment

Only authorized users are allowed to upload new attachments.

« This page (revision-14) was last changed on 25-Apr-2007 16:46 by ChuckSmith