(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 version . It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

After many long months of cooperation, we have finally reached a point where we can't find any more commonalities. The Creole 0.6 Poll shows that we can't reach consensus anymore. Although in WikiCulture, we would want consensus, when you have developers and users coming together across a wide range of Engines, there are inevitably going to be disagreements. The name Creole was chosen because we knew that the first common language would not be perfect, but good enough to make life easier for everyone using wikis.

Therefore, we think it's time now to submit a Creole 1.0 and not accept any more proposals. Moving forward, proposals now would only complicate WikiCreole, and we would like to have only basic wiki elements in the WikiCreole core and leave advanced elements for Creole Additions. This way the core is useful for wiki developers to integrate mixed edit mode into their wikis, while Creole Additions can be optionally implemented for advanced elements in wikis which need them.

We have used the Creole 0.6 Poll to influence the following decisions:

  • We have added an escape character (tilde) back to 1.0.
  • Space should not be required after list character, use Hyphen List Markup Proposal
  • There should be no explicit monospace font style, but don't define if nowiki is monospaced or not. Omit it and leave this to the developer while recommending the best practice of rendering monospace for in-line and block nowiki.

We are now calling the Creole 0.6 spec to be stable. For those of you who don't find their opinions in those decisions, please remember: Creole was designed to be a common markup, not a standard. Feel free to add a second way of doing things to your parser (see ExtensibleByOmission), which you probably have already done, but please support the least common denominator for the sake of unity and success of this spec. For the Creole 1.0 spec we will move all remaining proposals to be discussed as additions, and add a final word on InterWiki links (this has been forgotten so far, but its markup seems to be the same across most wiki engines).

In conclusion, we would like to propose that the current Creole 0.6 with the additional of InterWiki link syntax be renamed to Creole 1.0 and declared stable. We would also like to propose that there should be no significant changes to the core Creole for the next two years (see Goals). Work will continue on Creole Additions which will provide wiki developers a way to optionally integrate advanced elements of Creole into their wiki engines if desired. If there is no strong opposition, we would like to declare stable Creole 1.0 by 05-May-2007.

-- Christoph Sauer and Chuck Smith

Changes from Creole 0.6:

  • added interwiki links
  • more details about disambiguation of hyphens from signatures
  • nowiki monospace left to developer with best practice of making nowiki in-line and block to be monospace

See reasoning for more information about individual markup elements.

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#

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, nowiki can be used in list items, but they cannot span several list items. Whitespace is optional before and after the - or # characters. 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 by whitespace) ends the list. Note: a double hyphen should only be parsed as a second-level list when there is a bullet point on the line before or after it to avoid making signatures look like second-level list items.

Unordered Lists#

It is much easier to view lists with bold in them using a hyphen -, so it does not conflict with the asterisk (*) of bold. The multiple symbol 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
or:
-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
or:
#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, 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>

Links - Internal, External and Interwiki#

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

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 http://www.wikicreole.org/ http://www.rawlink.org/, http://www.another.rawlink.org Visit the WikiCreole website __Weird__ ''Stuff'' Ohana:WikiFamily


Paragraphs#

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

One or more blank lines end paragraphs. A list, table or preformatted 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.

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

Nowiki (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 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. We strongly recommend displaying nowiki text as monospace, but this is not required (also see: Proportional Font Nowiki Proposal).

Creole:

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

Recommended XHTML:

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

Sample Output:

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

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)#

Images are a common enough element on modern wiki pages to deserve their own markup. An exclamation point ! was not chosen as they are used by many wikis for emphasis. A prefix like "Image:" was not chosen because it's not obvious or friendly for non-English users. Wikis are still free to use prefixes in the image names if they are needed for denoting namespace, like in MediaWiki. 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, line breaks and preformatted/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

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

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 in certain combinations. 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.

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

Escape characters only trigger if you use it in combination with the occurrence of 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: ~

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      Combination Constraint              Example:
==============      ==========================          =========
Bold                Anywhere                            ~**
Italics             Anywhere                            ~//
Unordered Lists     Hyphen, first chars in line         ~-
Ordered Lists       First chars in line                 ~#
Headings            Equal signs, first chars in line    ~=
Links Open          Anywhere                            ~[[
Inside Links        Within Links                        [[A pipe ~| is used within links]]
Links Close         Anywhere                            ~]]
Line Breaks         Anywhere                            ~\\
Horizontal Line     First chars in line                 ~----
Image Open          Anywhere                            ~{{
Image Close         Anywhere                            ~}}
Table Open          First chars in line                 ~| this is | not a table
Inside Tables       Pipe used within a table cell       | x~|y |
Escaping Escape     Anywhere                            ~~
Escaping Escape     Anywhere                            ~<space>
Nowiki Open         First chars in line                 ~{{{
Nowiki Close        First chars in line                 ~}}}

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>

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> **

Mixed syntax examples#

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

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 particular version was published on 25-Apr-2007 15:07 by ChuckSmith.