DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:markdowku

markdowku Plugin

Compatible with DokuWiki

  • 2020-07-29 "Hogfather" no
  • 2018-04-22 "Greebo" yes
  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes

plugin Integrates Markdown into DokuWiki syntax

Last updated on
2020-06-06
Provides
Syntax
Repository
Source

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Hogfather

The version linked above is only compatible with DokuWiki versions up to Greebo.

For Hogfather RC2, please use this version of the plugin (last updated 2020-06-06). (The link should be updated once Hogfather is officially released).

Attention: The Markdowku plugin is not compatible with Hogfather RC2 (2020-06-01)!

In this release candidate, the old way of accessing Doku_Handler internals does no longer work and the new way does not yet work (see pull request #3122).

Workaround: upgrade to Hogfather RC2 and then manually apply these two patches from the pull request linked above:

cd /var/www/wiki/  # or wherever you DokuWiki root directory is
wget https://github.com/splitbrain/dokuwiki/pull/3122/commits/533aca443d11c7850d99ed088b80c85fdff14be3.diff -O - | patch -p1
wget https://github.com/splitbrain/dokuwiki/pull/3122/commits/eb33b670a5a7dd4886d1a52ffd9f44c4dc1063ad.diff -O - | patch -p1

Examples/Usage

This plugin will go before the overlapping DokuWiki syntax definitions and overrule them with Markdown specifications.

For patterns that are not part of Markdown, you can still use DokuWiki, e.g. you're still able to use DokuWiki tables.

Syntax

This plugins tries to resemble Markdown as closely as possible and does not extend it. It is a best-effort implementation - I didn't try to match the Markdown test suite, but rather provide a look-alike handler for Markdown syntax, as Markdown itself is somewhat underspecified.

You'll find the basic description on the website of the Markdown author, as well as a deeper description of the syntax.

If you encounter any incompatibilities in this version, feel free to add them here or report them.

Known incompatibilities

Due to the inner working of Markdown and DokuWiki, there are things which currently cannot be done with this plugin.

All in all, this plugin is complete. Just when it comes to nesting things, i.e. putting things into each other, this plugin doesn't handle lists and blockquotes well.

This should be a complete list of current general incompatibilities. Everything else is a bug:

  • nested in blockquotes:
    • codeblocks
    • paragraph handling
    • lists
    • multiline reflinks/refimages
  • 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.
  • conflict with bootstraps3 theme in bulleted lists

Why no nested content in lists?

From the old project page:

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

Development

Version History

Please note that this plugin is not actively developed at the moment.!

Markdowku was initially developed by Julian Fagir. Raphael Wimmer just made the plugin ready for Hogfather and moved the repository to GitHub. Contributions welcome.

Bugs/Issues

Please submit an issue on GitHub.

There are still some issues in the old bug tracker.

ToDo/Wish List

This plugin is not complete yet. Incompatibilities are listed above at Known incompatibilities.

Suggestions by the initial author:

  • In the end, I want to extend this plugin to be able to handle different markdown flavours (esp. Github), with a switch in the configuration to choose between those all.
  • A switch like <no_markdown> will allow to avoid problems with existing native markup pages. (jseto) – I'll see what is possible, but I think it will be difficult to implement that. (gnrp 13-09-23)
  • The plugin editor does not work together with markdown. Either have the possibility to disable it, or even better, make it work with Markdown (Celano 13-08-08, reformatted by gnrp 13-09-23)

Further suggestions (dinobib 15-05-25) and other anonymous commenters:

  • Html doesn’t work but html is correct markdown and really useful for things markdown can’t do. Even the <html></html> tags of DokuWiki doesn’t work either. I have allowed html in config options but the plugin just seems to ruin the page when it encounters any <tag>. FIXME
  • Second problem is that we use a lot the footnote syntax of markdown extra (a footnote syntax [^1] which become near a standard in markdown tools) https://michelf.ca/projects/php-markdown/extra/#footnotes. This addition would be very nice.
  • Reference-style links from classic markdown doesn’t works. http://daringfireball.net/projects/markdown/syntax#link
  • It would be nice if Commonmark would be supported!

FAQ

There are already two Markdown plugins, why do you write a third one?

The prior two plugins (markdown, markdownextra) work completely different. The other two just create a large container (either defined by <markdown> tags or a .md file ending) and parse everything inside them as Markdown.

This plugin adds Markdown to the DokuWiki syntax, i.e. it still uses DokuWiki definitions for lists, headers, etc. Thus, markdowku enables you to use internal links, mix Markdown with other plugins and other syntaxes and have clean section headers and media embedding.

Discussion

Plugin abandoned?

digineut 2018-12-15 17:03 According to the Internet Archive, the author's dokuwiki was last seen in 2016. My guess is that he is no longer using it and the plugin is abandoned. My suggestion is to ask his approval for creating a GitHub repo to continue development there.

ismirnov 2020-06-04 17:03 I have filed an issue documenting the breaking changes in Hogfather, but nor response. The License is not very forking friendly, but perhaps we can do a GPL/MIT rewrite.

raphman 2020-06-06 00:46 I have fixed the plugin, contacted the original author, and taken over maintenance for now with his blessing. @ismirnov: The original license is the standard 2-clause BSD license, nothing special. Github Repo with Fork

plugin/markdowku.txt · Last modified: 2020-09-20 13:11 by Aleksandr