User Tools

Site Tools



markdowku is a syntax plugin for Dokuwiki to have native Markdown inside Dokuwiki syntax.

Yes, there are already two plugins (markdown and markdownextra) providing markdown support for Dokuwiki, but there are flaws which make me write my own one.
The problem is that the existing ones just take a script which was originally written for Wordpress. They still contain strange tracking information or so (just to track the code, not the use of it) and several Wordpress-specific code.
They just take a large bunch of text (marked by <markdown /> tags or a .md file ending) and convert it to HTML all at once. They do not interact with other plugins or markup, e.g. you cannot use internal links by [[BlaBla]], or interact with the classes Dokuwiki or templates. At the time I started writing markdowku, it didn't even support TOCs.

You can find its repository here.


There are several incompatibilities this markdown plugin has:

  • anything nested in headers. This is not compatible with Dokuwiki.
  • nested in blockquotes:
    • multiline reflinks/refimages
  • bold/italic multiline
  • nested in lists:
    • codeblocks
    • quotes
    • multiline reflinks/refimages
    • ATX headers
    • Setext headers
    • horizontal rulers
  • codespans with more than five backticks (most probably never used)
  • using underscores to make text bold. Double underline is already used by Dokuwiki for underlining text (Markdown can't do that), and I think it's better to have the option for underlining. In general notation, you also rather use underscores for underlining than making text bold.

The reason behind these incompatibilities are conceptual differences between Markdown's and Dokuwiki's inner workings. Markdown takes a text as a whole and transforms it into HTML. On the way, it will re-parse blocks (i.e. lists or blockquotes), treating them as if they were standing on their own.

Here is an example for this:

> # Blabla
> Blabla

Markdown would see that there's a comment, and then reparse the whole thing with the comment brackets removed, but nested inside the comment, i.e. it would reparse

# Blabla

and finally produce a blockquote with a headline in it.

Dokuwiki, on the other hand, uses a lexer you can pass tokens (regexes) to be matched. Visually spoken this means that Dokuwiki parses text only sequentially, while Markdown parses text also “vertically”. Overcoming this is difficult and the main reason that nesting is not yet implemented for most formatting.

Ideas, plans

Markdown is an incomplete markup language. Many projects need something Markdown doesn't offer: Tables. And besides tables, there are other shortcomings some projects didn't want to follow, so they implemented Markdown, but created their own dialect.

There are reasons for each of them, and they all have some nice parts. My goal is to implement some of these dialects, starting with Github flavoured Markdown, and provide a configuration option to choose the dialects you want to activate.

Version history

  • 2014-04-21 53f7bcb5de
    • Eleventh release. Add the possibility to use shortcut reference links/anchors, as proposed by Jason. Thank you for reporting that!
  • 2014-02-17 1d55447ead
    • Tenth release. Fix some smaller bugs, nothing great.
  • 2013-04-03 9135aa8d9a
    • Ninth release. Ensure markdowku works with Dokuwiki “Weatherwax”. Remove m modifier for regexes in favour of parsing newlines, and make sure trailing newlines are always non-matched with positive lookaheads. Make multiline bold/italic work, but sometimes this might break with list formatting (then, you have to escape one).
  • 2013-02-11 edd3ba2e78
    • Eight release. Fixing code to work with PHP 5.4 and making escapes work.
  • 2013-01-20
    • Seventh release. Github-style code blocks added.
  • 2013-01-19
    • Sixth release. List paragraph handling improved (now, you can have paragraphs inside a list). Plus, list indentation now works right and orients on the width of the former element. Minor improvements about the class types.
  • 2013-01-03
    • Fifth release. Blockquotes aren't yet handled nicely, but they are rendered, and ATX and Setext headers and horizontal rulers work nested in them.
  • 2012-12-29
    • Fourth release. Serious security issue fixed (thanks to Michitux), all direct xhtml tags added are replaced by corresponding calls to the renderer
  • 2012-12-28
    • Third release. Reference links work.
  • 2012-12-27
    • Second release, blockquotes work, but nothing nested in them. Bugs with formatting following setext headers and codeblocks fixed.
  • 2012-12-23
    • Initial release, still not finished.
projects/markdowku.txt · Last modified: 2014-09-12 18:40 by gnrp