This is the proposed v1.0 spec of Creole (2007-May-09), under discussion until 2007-Jun-13.  Also see [[Roadmap to Creole 1.0]], [[Creole 1.0 Poll]] and [[reasoning]] for more information.  Note that [[Creole 0.7]] was rejected.

Changes from [[Creole 0.6]]:
* replaced hyphen with asterisk for bullet lists
* added interwiki links
* use three angle brackets {{{<<<>>>}}} instead of two chars for placeholder
* added escape character to core (as requested in [[Creole 1.0 Poll]]) with exception to URLs
* changed escape character so it only escapes following character (as requested in [[Creole 1.0 Poll]])
* removed escaping closing nowiki triple curly brackets because this is now covered by the escape character

[{TableOfContents title='Overview'}]

== Bold and Italics

Bold and italic text can be used inside paragraphs, list items and table cells.
Links appearing inside bold and/or italic text should also become bold and/or italic. 
The bold/italic text will end at the end of paragraphs, list items and table cells -- thus it cannot span several of them.

=== Bold

Creole:
{{{ **bold** }}}

Recommended XHTML:
{{{ <strong>bold</strong> }}}

Sample Output:
__bold__

**Reasoning:** 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. [[Bold and Italics Reasoning|More details]]

=== Italics

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

Creole:
{{{ //italics// }}}

Recommended XHTML:
{{{ <em>italics</em> }}}

Sample Output:
''italics''

**Reasoning:** A slash ({{{/}}}) looks like slanted italics, so it is intuitive and thus easier to remember. [[Bold and Italics Reasoning|More details]]

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, nowiki can be used in list items, but they cannot span several list items.  Whitespace is optional before and after the * or # characters, 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, although it can contain line breaks forced with {{{\\}}}.  It is recommended to have support for a depth of at least five levels of nesting. Any line that does not start with a {{{*}}} or {{{#}}} (optionally preceded with some whitespace) ends the list.

**About unordered lists and bold:** a line starting with {{{**}}} (including optional whitespace before and afterwards), immediately following any list element on 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

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

**Reasoning:** 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. [[Lists Reasoning|More details]]

=== Ordered Lists

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:
# Item 1
## Item 1.1
# Item 2

**Reasoning: ** The number sign ({{{#}}}) is used for ordered lists in most wikis. [[Lists Reasoning|More details]]

== Headings

Only three different sized levels of headings are required.  Closing (right-side) equal signs are optional, don't need to be balanced and don't impact the kind of heading generated. Whitespace is not allowed before the left-side equal signs.  Only whitespace characters are permitted after the closing equal signs.  No markup has to be parsed within 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>
}}}

**Reasoning:** 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. [[Headings Reasoning|More details]]

== Links - Internal, External and Interwiki

Links can appear in paragraphs (also inside bold and italic text), list items and table cells. The links are bold or italic if they are part of bold or italic text. At least images inside links must be supported. Parsing other markup within a link is not required (optional).

Free-standing urls should be detected and turned into links. Single punctuation characters ({{{,.?!:;"'}}}) at the end of urls should not be considered part of the url.

If your wiki supports Interwiki links, links to other wikis should be made by putting the wiki name, then a colon in front of the page title. For example, linking to {{{ [[WikiCreole:Creole1.0]] }}} would link to the Creole spec on this WikiCreole wiki.

Creole:
{{{
[[link]]
[[MyBigPage|Go to my page]]
[[http://www.wikicreole.org/]]
http://www.rawlink.org/, http://www.another.rawlink.org
[[http://www.wikicreole.org/|Visit the WikiCreole website]]
[[Weird Stuff|**Weird** //Stuff//]]
[[Ohana:WikiFamily]]
}}}

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.another.rawlink.org">http://www.another.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>
<a href="http://wikiohana.net/cgi-bin/wiki.pl/WikiFamily">Ohana:WikiFamily</a>
}}}

Sample Output:

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

**Reasoning:** 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. [[Links Reasoning|More details]]

== Paragraphs

One or more blank lines end paragraphs.
A list, table or nowiki block end paragraphs too.

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.

**Reasoning:** No markup tags should be necessary to start a new paragraph. [[Paragraphs and Line Breaks Reasoning|More details]]

== Line breaks

 {{{ \\ }}} (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

**Reasoning: ** __blog-style vs. wiki-style__\\
There was a [long discussion|Talk.Change Linebreak Markup Proposal] 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. [[Paragraphs and Line Breaks Reasoning|More details]]

== Nowiki (Preformatted)

This works inline or as a block. __No wiki markup is interpreted between these characters.__ 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.  In a block, characters are displayed in monospace. For inline nowiki text, wiki implementers can decide whether to display this text regularly or in monospace.

**Note:** if you need a more general purpose escape character, please see [[Additions]].

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>** &lt;i&gt;this&lt;/i&gt; **</tt>
}}}

Sample output:

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

**Reasoning: ** 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. [[Preformatted and Nowiki Reasoning|More details]]

== Horizontal Rule

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 /> }}}

**Reasoning:** All non-WYSIWYG wikis use hyphens ({{{----}}}) to denote horizontal rules.  Most wikis require four. [[Horizontal Rule Reasoning|More details]]

== Image (inline)

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

Recommended XHTML:
{{{ <img src="myimage.png" alt="this is my image"/> }}}

**Reasoning:** The most common image markup was double curly brackets ({{{ {{}} }}}) which will then have the same internal structure as links for consistency. [[Images Reasoning|More details]]

== Tables

All cells are separated by single pipes.  The ending pipe is optional.  You can embed links, bold, italics, line breaks, and nowiki in table cells.  Equal sign directly following pipe defines a header.  Headers can be arranged horizontally or vertically.  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>
<th>Heading Col 1</th>
<th>Heading Col 2</th>
</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

**Reasoning:** 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. [[Tables Reasoning|More details]]

== Placeholder

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)

**Note:** do not confuse this with the plug-in syntax which can be found at [[Additions]].

Creole:
{{{ <<<x>>> }}}

**Reasoning:** This is the only new markup introduced in Creole. This was mainly developed due to MediaWiki's extensive use of special characters making it practically impossible to implement Mixed Creole mode. Few wikis use angle brackets ({{{<<<>>>}}}) for markup. This markup is generated by the wiki engine rather then typed in by the user, therefore we use three instead of two markup characters to reserve the markup with two angle brackets for extension elements that are typed in by users. [[Placeholder Reasoning|More details]].

==Escape Character

It is often troublesome to use the nowiki in-line to display symbols of wiki syntax, so it would be useful to have an escape character that could be put before wiki syntax to prevent it from being interpreted. The tilde was chosen not to conflict with line breaks and because it is a very infrequently used character. It is not generally easy to type, but it will also not need to be used often, so in this sense it is also suitable.

The escape character only escapes the character immediately following it. This means that e.g. the tilde in this use case is displayed as tilde and not escaped. It would certainly **never** escape if followed by a space or an alphanumeric character.  However, if a wiki uses CamelCase, it is recommended that a tilde in front of a CamelCased phrase keep it from becoming a link.  Also note that tildes within URLs should not be escaped.

{{{
http://stud.hs-heilbronn.de/~someone
}}}

Escape characters only trigger if you use it in combination with a character that has special meaning in creole and would otherwise be rendered as markup. For example if you use "tilde + equal sign as first characters in a line" it will escape the equal sign and display it as such because otherwise it would be rendered as heading.

{{{
=Heading
~=Line starting with equal sign, this displays a normal tilde: ~
~=~=~= Line starting with three equal signs
}}}

If an escape character is only used in certain combinations we have a minimum of collisions with existing markup. For example if an wiki uses tilde as normal markup, it would not collide with e.g. 

{{{
~=This is a heading
~this is subscript in certain wikis~
~~=This is a sentence with a tilde and an equal sign at the beginning... (tilde escapes itself)
}}}

Here's a complete list that would cause the escape character (e.g. tilde) to trigger escaping of the following character combinations. This can be extended as need be. Note also that an escape character can be escaped by putting a space after it, since a space cannot be escaped.

{{{
Escapes Markup      Example:
==============      ========
Bold                ~*~*
Italics             ~/~/
Unordered Lists     ~-
Ordered Lists       ~#
Headings            ~=
Links Open          ~[~[
Inside Links        [[A pipe ~| is used within links]]
Links Close         ~]~]
Line Breaks         ~\~\
Horizontal Line     ~-~-~-~-
Image Open          ~{~{
Image Close         ~}~}
Table Open          ~| this is | not a table
Inside Tables       | x~|y |
Escaping Escape     ~~
Escaping Escape     ~<space>
Nowiki Open         ~{~{~{
Nowiki Close        ~}~}~}
}}}

So, for example, this markup:

{{{
{{{
int main(int argc, char *argv[]) {
 if argc>0 {
   if argc<=1 {
     --argc;
~}~}~}
~}}}
}}}

will produce this result:

{{{
<pre>
int main(int argc, char *argv[]) {
 if argc>0 {
   if argc<=1 {
     --argc;
~}}}
</pre>
}}}

**Reasoning:** Users should be able to escape markup characters (or all non-alphanumeric characters) with a special character. It's often faster to type and more readable than using nowiki (3+3 curly braces). In order to allow spaces in front of lists, which is a quite common practice in wiki engines, it should be a escape character other than space. This way, stars, slashes and other markup characters, when found in the original text, can be easily escaped, to be rendered as themselves. [[Escape Character Reasoning|Reasoning]]

== Bold and/or italic links
Creole:
{{{
//[[Important page|this link is italicized]]//
**[[Important page]]**
//**[[Important page]]**//
}}}

Recommended XHTML:
{{{
<em><a href="http://www.examplewiki.com/Important_Page">this link is italicized</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 italicized|Important page]''\\
__[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
# item about a [certain page]
# {{{//this// is **not** [[processed]]}}}