A not so short introduction to Creole and Creole2docDeutsch

You are here: RubydocgeneratorCreole2doc


Creole is a common wiki markup language to be used across different wikis. More about Creole can be found at http://www.wikicreole.org/

I decided to implement a creole-interface creole2doc for my docgenerator.

This is a short description, on how to use this creole2doc-implementation.

There is always the code and the result:

Sourcecode and result

Sourcecode and result

One remark: creole2doc is no Wiki! It is a document generator, based on docgenerator.rb, using the creole wiki syntax. So there are some differences in linking. There are no Inter-wiki-links (there is no wiki). But there are links to other files on your file system.

Usage in Ruby

You can create ruby scripts to generate documents. One big advantage: You have one source and you can build HTML or LaTeX-files.


require 'creole/creole2doc'
doc = Creole_document.new(
  :title => 'A not so short introduction to Creole',
  :shorttitle => 'Creole',
  :with_toc => true
#Add the content
doc << DATA
#File.open('wiki.txt'){|file| doc << file } 
doc.save('creole.tex') #build the LaTeX-code

=Document start
Here is your wiki text.


Pros and Cons

Why you should use it

Why you shouldn't use it

Well, you can use it. There are some restrictions:

Base elements


Sections are defined by = at the start of a line.

Differences to creole-standard:

The level for the section are following the rule:

This rule can by modified by the option :title_levels

Table of contents

You can build a table of contents from your wiki-text. The table of contents will be a nested list with all heading entries. Details see ruby docuemntation.

Generell Markup

Paragraphs and Linebreaks

With an empty line you get different paragraphs.

This is the second paragraph

With an empty line you get different paragraphs.

This is the second paragraph

Manual Line breaks

Two backslashes create a newline\
TeX-useres are welcome ;-)

Two backslashes create a newline
TeX-useres are welcome ;-)

(Here's a little problem with the two backslashs and the display in the source. There are really two \ in the source)


You can make things **bold** or //italic// 
or **//both//** or //**both**//.

You can make things bold or italic or both or both.

Separator line




  1. one
  2. two
  3. three

Mixages are possible:



[[http://ruby.lickert.net|My Ruby page]]

[[#links|Page internal link]]


My Ruby page

Page internal link

Verbatim/no Wiki

Use three curly brackets for original code
Use three curly brackets for original code

Easy Tables

Creole allows to build some easy tables.

|=header col1|=header col2| 
|you         |can         | 
|also        |align\ it. | 
header col1 header col2
col1 col2
you can
also align

I don't recommend this tables. I prefer a solution with placeholders


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)


Special rule: After the >>> you have to add which placeholder you work with.

Placeholder or often used in creole2doc.

under development:

Restricted Wiki text

Wiki text only for LaTeX


  \textbf{This}  is only for LaTeX.

Wiki text only for HTML

  <em>This</em>  is only for HTML.
This is only for HTML.

Your own placeholders

With a bit of Ruby-Knowlwdge you can define your own placeholders.

For this document I created a 'testcase'-placeholder to compare the code and the result.

class Creole_testcase < Creole_placeholder
  #Return content only for html
  def to_doc( target, options = {})
      element(:div,{ :class => 'source'}, element(:verbatim,{},@source.join)),
      element(:div,{ :class => 'result'}, Creole.new( :content => @source.map{|x|x.sub(/^\s*(\S)/,'')}.join )),
      element(:br, :clear => 'all'),
    ].to_doc( target, options)
end #Creole_html 
wiki = Creole.new()
wiki.placeholders['testcase'] = Creole_testcase 

Tables similar to Wikimedia

Creole allows also to build easy tables

I prefer the Wikimedia syntax for tables. To provide LaTeX-tables some additional informations are available.

  before **a**

before a

1 2 3
eins zwei drei
one two three



Not realized up to now.


Inclusions are things that are included in your resulting document.

According the creole-standard 1.0 this are mainly pictures. I extended it by more features for my personal use. Other extensions are built in as Plugin

All extensions are build in the same way:


You have a key for the inclusion, then a description and afterwords a list of options. Description and options are optional.


Images are added quite simply:


{{Red_Flower.jpg|red flower}}

red flower

The description is used as "alt"-text.

In addition to the creole 1.0 standard you can use additional options.

Add CSS-information

You can add some css-information for the image:

{{Red_Flower.jpg|red flower|css=width:50px}}
{{Red_Flower.jpg|red flower|imgcss=width:100px}}

red flower red flower

There is no difference between the option css and imgcss.

Add CSS-classes

Instead of direct css you can define a class:



This makes sense if you add something like

img.img100 { width: 100; border: double; border-color: green; }

Aligment, width, link

You can define aligment and width via the css-command:

{{Red_Flower.jpg|red flower|css=width:50px;float:left}}

Links can be added also:

[[<<yourlink>>|{{Red_Flower.jpg|red flower}}]]


Plugins are parts of the wiki, where the usage is no Creole-standard, but the definition corresponds to the standard.

All plugins are build in the same way:


You have a key for the plugin, then a description and afterwords a list of options. Description and options are optional.

Footnotes and Footnote groups

You can add footnotes to your text. With footnotes you get the footnotes.

Hi<<footnote|Remark one>>

Hi again!<<footnote|Remark two>>


Hi again!2

1Remark one
2Remark two

The output of the footnotes makes no sense with LaTeX. 1

Your own labels

If you want, you can define your own label:

<<footnote|This is a footnote|label=mylabel>>


This works only for HTML, not LaTeX

Multiple footnote groups

If you need it, you can build different groups of footnotes.

One usage could be footnotes inside tables. You could build a group for this footnotes and print it after the table. In LaTeX you don't need this groups, with minipages you get this feature automatic.

Hi<<footnote|This is a footnote>>

Hi again!<<footnote|This is another footnote|groupid=other>>



Hi again!1

1This is a footnote

1This is another footnote

1LaTeX is already putting the footnotes to the text.
2Don't forget: eval is evil

Inline Ruby

You can add Inline-Ruby in your creole Code. There are two different variants.

Raw data

The rubycode is added unchanged to the wiki.

1 + 1 = <<ruby_raw|1+1>>

1 + 1 = 2

Parsed data

The ruby code is parsed by the wiki before it is added:

1 + 1 = <<ruby|1+1>>


1 + 1 =




Just to explain the output: The command part of the plugin is executed (with eval2) . The result is used as input to the wiki and is parsed by the wiki. And so you get new paragraphs for the result.

An example for the usage

Just one example for the usage:


This wiki-code will load and display the content of the file mydata.txt.