DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:creole

Creole Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin Creole Markup for DokuWiki

Last updated on
2020-12-13
Provides
Syntax
Repository
Source
Conflicts with
ckgedit, mathjax

Description

Creole is an initiative to bring a common basic set of wiki markup to different wiki engines. The Creole 1.0 Specs (2007-07-04) are very close to the syntax used by DokuWiki. Only those elements differ:

This plugin will interpret Creole elements that are not understood by DokuWiki. If the markup collides (as with the header level order), by default DokuWiki's standard markup takes precedence.1) With the exception of the changed behaviour for linebreaks, all your existing wiki pages will look the same.

If you use this plugin to support the Creole syntax, you might want to list your wiki at http://www.wikicreole.org/wiki/WikisSupportingCreole

Installation

To install the Creole plugin

  • Go to the Admin page and then Extension Manager
  • Search for the plugin “Creole” at the Search and Install tab
  • Use the Install button

In the Configuration Settings you can change the Markup precedence over the DokuWiki syntax if you like.

:!: Since release 2020-08-21 the creole plugin is incompatible with DokuWiki release Greebo and the releases before it. If you are using DokuWiki releases before Hogfather then the latest compatible release is 2019-02-06. :!:

Components

Listblock

Creole style ordered and unordered lists use a slightly different markup:

Creole (and DokuWiki):

* Item 1          (  * Item 1     )
** Item 1.1       (    * Item 1.1 )
* Item 2          (  * Item 2     )

Output:

  • Item 1
    • Item 1.1
  • Item 2

Creole (and DokuWiki):

# Item 1          (  - Item 1     )
## Item 1.1       (    - Item 1.1 )
# Item 2          (  - Item 2     )

Output:

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

Reverse Headings

In Creole, the header ordering is just the other way round. If you have set the markup precedence option to DokuWiki (default), this plugin will assume headers are DokuWiki style if there are equal signs after the title. In Creole, closing (right-side) equal signs are optional. So if you omit them, headers are interpreted as Creole.

Creole (and DokuWiki):

= Level 1        (====== Level 1 ======)
== Level 2       (===== Level 2 =====  )
=== Level 3      (==== Level 3 ====    )
==== Level 4     (=== Level 4 ===      )
===== Level 5    (== Level 5 ==        )

Output:

Level 1

Level 2

Level 3

Level 4

Level 5

Linebreaks

DokuWiki and Creole 1.0 do not care about (single) line breaks. Creole 0.3, however, does treat line breaks in the source as line breaks in the output. This component is mainly the same as Chris Smith's linebreak plugin. Thanks!

Previous versions of this plugin matched Creole 0.3 and so linebreaks were kept as linebreaks. From now on, linebreaks will be replaced by whitespace to match Creole 1.0. The config option linebreak can be set to Linebreak to switch back to the Creole 0.3 behaviour and keep the linebreaks.

Preformatted

Creole:

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

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

Output:

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

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

Tables

Creole (and DokuWiki):

|Heading Col 1  |Heading Col 2 |   (^Heading Col 1  ^Heading Col 2 ^)
|Cell 1.1       |Cell 1.2      |   (|Cell 1.1       |Cell 1.2      |)
|Cell 2.1       |Cell 2.2      |   (|Cell 2.1       |Cell 2.2      |)

Output:

Heading Col 1 Heading Col 2
Cell 1.1 Cell 1.2
Cell 2.1 Cell 2.2

The difference to DokuWiki is that in Creole there's no special markup for header cells and no cell alignment. In turn, in Creole the ending pipe is optional.

Subscript

Creole:

This is ,,subscripted,, text.

Output:

This is subscripted text.

Superscript

Creole:

This is ^^superscripted^^ text.

Output:

This is superscripted text.

Monospace

Creole:

This is ##monospace## text.

Output:

This is monospace text.

Bugs / Feature Requests

Please report bugs or feature requests at the Bug tracker.

Further Resources

Changes

Todo

  • make toolbar work
  • update to Creole 1.0 specs (work in progress)
  • …but there must be a conf option to change linebreaks between Creole 0.3 and 1.0. Done.

Discussion

Very nice! The image notation in the Creole Markup however conflicts with the syntax for plugins in DokuWiki. If DokuWiki is planning to change at some point in time to Creole, it might be wise to switch to the proposed 'internal markup' style «x» for plugins. For anyone to use this plugin, a modification of the toolbar would be needed; do I have to change the toolbar manually or could the plugin be able to override the inserted syntax? Also, is there any converter for existing wiki pages? — Niklas 2006-12-19 09:16

I don't know if a plugin can override the toolbar code, but I hard-coded reversed headings some time ago using these tips. With the Creole plugin installed, all you have to change is the headings section in toolbar.php (to get an idea: look here.
As for the converter: I once thought about writing a little script, but then decided to make it by hand. But if you want to do so. It should be relatively easy: Just go trough the text of each of your pages (with old syntax) and replace each occurrence of a headline with a unique symbol (like '======' → 'XXXH1XXX', '=====' → 'XXXH2XXX' …). Then you go through the text again and replace your unique identifiers with the new syntax ('XXXH1XXX' → '==', 'XXXH2XXX → '===' …). By going through the text twice, you avoid conflicts of old and new headline syntax.
As for the other syntax changes: You don't have to change anything, as DW understands both old and new syntax for lists and no-wiki. — konstantin baierer 2006-12-19 15:47
Good point about the replacement. The reverse header tags page is only semi-useful to me: I really don't want to patch a single line of code, I only want to use plugins that can be installed via the plugin manager. The reason is that even though I am setting up the wiki and hacking around is no problem at all, I won't be the one maintaining it in the future, so I should and will not assume that the future maintainer will be able to cope with actual source code. Niklas 2006-12-19 23:32
Hi Niklas and Konstantin. With an additional event hook in inc/toolbar.php, it would finally be possible for plugins to modify the toolbar. Let's ask Andi and the other developers whether they are open for this idea. — Esther Brunner 2006-12-20 00:53
As I had to make a fresh installation today, I wrote that script mentioned above in Perl. It reverses all header tags from DokuWiki to Creole notation for a file given as argument.
#!/usr/bin/perl -w
# revheaders
# Convert DokuWiki headers to Creole headers
 
foreach (@ARGV) {
    $original = $metaformat = '';
    $filename = $_;
    open WIKIPAGE, ("<$filename");
    while (<WIKIPAGE>){
        $original .= $_;
        $_ =~ s/^======(.*)+?(======)/Xh1hX$1/g;
        $_ =~ s/^=====(.*)+?(=====)/Xh2hX$1/g;
        $_ =~ s/^====(.*)+?(====)/Xh3hX$1/g;
        $_ =~ s/^===(.*)+?(===)/Xh4hX$1/g;
        $_ =~ s/^==(.*)+?(==)/Xh5hX$1/g;
        $metaformat.= $_;
    }
    $metaformat =~ s/^Xh1hX(.*)/==$1==/gm;
    $metaformat =~ s/^Xh2hX(.*)/===$1===/gm;
    $metaformat =~ s/^Xh3hX(.*)/====$1====/gm;
    $metaformat =~ s/^Xh4hX(.*)/=====$1=====/gm;
    $metaformat =~ s/^Xh5hX(.*)/======$1======/gm;
    open BACKUP, ">$filename.BAK";
    print BACKUP $original;
    open WIKIPAGE, (">$filename");
    print WIKIPAGE $metaformat;
}
The original file is overwritten, a backup is made to oldname.BAK.
If you want to convert a single file, just type perl revheaders FILENAME. To rename a whole directory, go to the base of it and type find . -regex '.*txt' | xargs perl revheaders. That will convert all .txt-files in this and all subsequent folders. If you want to undo your changes, just run the script again with the same file(s). It's especially useful to mass rename the built-in wiki pages in /inc/lang/. — konstantin baierer 2007-03-31 22:27

I couldn't resist re-writing that Perl script into a one-liner command (for Mac or Linux - Windows would need different quoting) with a single regex. Admittedly, it's less readable than Konstantin's script, but I like the single formula to revert the number of “=”. The -i.bak option makes it do the replacements in-place, saving the original with a .bak extension.

perl -i.bak -pe 's/^(={2,6})(.*?)\1/"="x(2+abs(length($1)-6)).$2/e' YOUR_ORIGINAL_FILE.txt

To do it on a whole folder (but be sure to be in the right folder!):

perl -i.bak -pe 's/^(={2,6})(.*?)\1/"="x(2+abs(length($1)-6)).$2/e' *.txt

Or by searching, also in subfolders:

find /path/to/wiki/data/pages -type f -name "*.txt" -exec perl -i.bak -pe 's/^(={2,6})(.*?)\1/"="x(2+abs(length($1)-6)).$2/e' "{}" \;

Albert25 2019-09-24 18:24

Thank you, for this very nice plugin. — Rick Companje 2007-12-20 17:52

Wanted to point out that going to Creole 1.0 is not a big leap. I wrote a couple additions for the Creole 1.0 Additions of subscript ( ,, )and strikeout ( – ). Took a couple minutes, can't get superscript to work ( ^^ ) regardless of sort, always get intercepted as a table. even updated the toolbar to support the new syntax. – Brian Hartvigsen 2008-02-23 13:27

I actually got superscript and the new table header syntax working. The later is probably a dirty hack, but it works ;-)Brian Hartvigsen 2008-02-23 13:27
Nice, if you don't mind sharing your work patches are always welcome. Just got the mail :-). — Michael Klier 2008-02-24 11:42

There is a problem with the parser. An expression like //italics// = italics is misinterpreted and starts a new chapter section! — Morten Nielsen 2009-02-17 14:41

Also, a new chapter is started when you try to put a double-stroked right arrow (⇒, =>) at the Beginning of a line. — Benjamin Molitor 2009-03-15 09:53

Creole 1.0 has already been out, any plan to update this plugin to support it? — DAY 2010-01-22 14:18

To make '|=' working (table heading),I directly edited two files of dokuwiki like below. Can anyone include these to creole plugin?? — goldseed 2010/09/05 10:56

parser.php line 434

//-------------------------------------------------------------------
class Doku_Parser_Mode_table extends Doku_Parser_Mode {
 
    function Doku_Parser_Mode_table() {
        global $PARSER_MODES;
 
        $this->allowedModes = array_merge (
                $PARSER_MODES['formatting'],
                $PARSER_MODES['substition'],
                $PARSER_MODES['disabled'],
                $PARSER_MODES['protected']
            );
    }
 
    function connectTo($mode) {
        $this->Lexer->addEntryPattern('\n\^',$mode,'table');
		$this->Lexer->addEntryPattern('\n\|=',$mode,'table');  // changed!!!
        $this->Lexer->addEntryPattern('\n\|',$mode,'table');
    }
 
    function postConnect() {
        $this->Lexer->addPattern('\n\^','table');
		$this->Lexer->addPattern('\n\|=','table');  // changed!!!
        $this->Lexer->addPattern('\n\|','table');
        $this->Lexer->addPattern('[\t ]*:::[\t ]*(?=[\|\^])','table');
        $this->Lexer->addPattern('[\t ]+','table');
        $this->Lexer->addPattern('\^','table');
		$this->Lexer->addPattern('\|=','table');  // changed!!!
        $this->Lexer->addPattern('\|','table');
        $this->Lexer->addExitPattern('\n','table');
    }
 
    function getSort() {
        return 60;
    }
}

handler.php starting line 578

     function table($match, $state, $pos) {
        switch ( $state ) {
 
            case DOKU_LEXER_ENTER:
 
                $ReWriter = & new Doku_Handler_Table($this->CallWriter);
                $this->CallWriter = & $ReWriter;
 
                $this->_addCall('table_start', array(), $pos);
                if ( (trim($match) == '^') or (trim($match) == '|=') ) { // changed!
                    $this->_addCall('tableheader', array(), $pos);
                } else {
                    $this->_addCall('tablecell', array(), $pos);
                }
            break;
 
            case DOKU_LEXER_EXIT:
                $this->_addCall('table_end', array(), $pos);
                $this->CallWriter->process();
                $ReWriter = & $this->CallWriter;
                $this->CallWriter = & $ReWriter->CallWriter;
            break;
 
            case DOKU_LEXER_UNMATCHED:
                if ( trim($match) != '' ) {
                    $this->_addCall('cdata',array($match), $pos);
                }
            break;
 
            case DOKU_LEXER_MATCHED:
                if ( $match == ' ' ){
                    $this->_addCall('cdata', array($match), $pos);
                } else if ( preg_match('/:::/',$match) ) {
                    $this->_addCall('rowspan', array($match), $pos);
                } else if ( preg_match('/\t+/',$match) ) {
                    $this->_addCall('table_align', array($match), $pos);
                } else if ( preg_match('/ {2,}/',$match) ) {
                    $this->_addCall('table_align', array($match), $pos);
                } else if ( $match == "\n|" ) {
                    $this->_addCall('table_row', array(), $pos);
                    $this->_addCall('tablecell', array(), $pos);
                } else if ( $match == "\n^" ) {
                    $this->_addCall('table_row', array(), $pos);
                    $this->_addCall('tableheader', array(), $pos);
                } else if ( $match == '|' ) {
                    $this->_addCall('tablecell', array(), $pos);
                } else if ( $match == '^' ) {
                    $this->_addCall('tableheader', array(), $pos);
		}  else if ( $match == '|=' ) {       // changed!
                    $this->_addCall('tableheader', array(), $pos);
                }
            break;
        }
        return true;
    }

Has problem with dokuwiki-2010-11-07.tgz “Anteater”. Is there anyone can fix it?

Problem is fixed in current version. — Benjamin Molitor 2010-12-04 18:07

I haven't account at Github, so I will write here, sorry.

I found a little bug: There is something wrong when I type: =>

It should be rendered as an arrow mark (⇒), but with this plugin i've got something like this (HTML preview):

<h1><a name="section" id="section">&gt;</a></h1>

You can see it e.g. at the syntax page with this plugin installed, even if dokuwiki syntax precedence is enabled.

orinoco 2011-03-05 19:50


A big thank you to all of you who have created and maintained this plugin. It provides me interoperability with WordPress where I use the BlogText Creole markup plugin. I have enhanced the Creole DokuWiki code running on my computer and would like to share what I have done. Perhaps what I have done, or something like it, could become a part of the standard release.

I enhanced the plugin to support this sort of syntax that I often use (example):

Host file setup:
# **Desktop Link to Hosts File.** Log in as the Administrator OS user, bring up a Cygwin command window to create a link to the hosts file using the following commands: {{{
cd /cygdrive/c/Users/Administrator/Desktop/

ln -T /cygdrive/c/Windows/System32/drivers/etc/hosts hosts.txt
}}}
# **Add Mac host to hosts file.** Still logged in as the Administrator OS user, add the following line to the hosts file using the hosts.txt desktop link: {{{
10.180.15.2	mymac
}}}

I enhanced the plugin to switch to block mode for an inline nowiki section that ends with three braces immediately after a newline. Regular inline mode takes precedence - the switch to block mode only happens if there is no normal (i.e., not right after a newline) set of end braces.

Here are the changes:

(1) In preinline.php, only match entry if there is no newline before the terminating braces - I added the [^\n] construct. Here is the connectTo function with that small change:

    function connectTo($mode) {
        // swg added check for not newline character (not block mode)
        $this->Lexer->addEntryPattern(
                '\{\{\{(?=.*?[^\n]\}\}\})',
                $mode,
                'plugin_creole_preinline'
                );
    }

(2) Added a second preinline class file, called preinline2.php, for catching the case of an inline nowiki section with a block terminator. Here is the entire file contents:

<?php
/**
 * Creole Plugin, inline preformatted component: Creole style preformatted text
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Esther Brunner <wikidesign@gmail.com>
 */

// must be run within Dokuwiki
if(!defined('DOKU_INC')) die();

if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');

/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_creole_preinline2 extends DokuWiki_Syntax_Plugin {

    function getInfo() {
        return array(
                'author' => 'Gina Häußge, Michael Klier, Esther Brunner, Sam Gabriel',
                'email'  => 'sam_gabriel@yahoo.com',
                'date'   => '2012-08-17',
                'name'   => 'Creole Plugin, inline preformatted component',
                'desc'   => 'Creole style preformatted text',
                'url'    => 'http://wiki.splitbrain.org/plugin:creole',
                );
    }

    function getType() { return 'protected'; }
    function getSort() { return 103; }

    function connectTo($mode) {
    	// swg added check for newline indicating block mode
        $this->Lexer->addEntryPattern(
                '\{\{\{(?=.*?\n\}\}\})',
                $mode,
                'plugin_creole_preinline2'
                );
    }

    function postConnect() {
        // swg added newline
        $this->Lexer->addExitPattern(
                '\n\}\}\}',
                'plugin_creole_preinline2'
                );
    }

    function handle($match, $state, $pos, &$handler) {
        switch ($state) {
            case DOKU_LEXER_ENTER:
                $handler->_addCall('monospace_open', array(), $pos);
                break;
            case DOKU_LEXER_UNMATCHED:
                // swg changed unformatted to preformatted
                $handler->_addCall('preformatted', array($match), $pos);
                break;
            case DOKU_LEXER_EXIT:
                $handler->_addCall('monospace_close', array(), $pos);
                break;
        }
        return true;
    }

    function render($mode, &$renderer, $data) {
        return true;
    }
}
// vim:ts=4:sw=4:et:enc=utf-8:

Sam Gabriel 2012-08-17 22:29

Creole conflicts with fckglite

I just learned the hard way, that the creole plugin conflicts with the wysiwyg editor plugin fckglite. If creole is installed, fckglite refuses to save. Depending on circumstance, the section to be edited gets deleted. There are no error messages in /var/log/apache/error.log . Apparently, creole does not even have to be enabled to produce this failures. kmk 2012-09-17 20:05

The needed include file for above solution:
isfckgLiteOn.inc
<?php
function fckgLiteOn() {
 
if(isset($_COOKIE ['FCK_NmSp']) && isset($_COOKIE ['FCKW_USE'])) {
   return false;
}
return true;
 
}

Myron Turner 2012/09/21 16:57

1)
You can change the markup precedence to Creole with the config manager, if you want full Creole support.
plugin/creole.txt · Last modified: 2023-04-11 22:45 by bmolitor

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki