MarkdownExtra Plugin

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

• https://github.com/naokij/dokuwiki-plugin-markdownextra/tarball/master
• Or: http://madpropellerhead.com/projects/markdownextra.tgz
• Or: https://bitbucket.org/jpulakka/markdownextra-plugin-for-dokuwiki/downloads/markdownextra.tgz

This plugin is available on both GitHub and Bitbucket:

• https://github.com/naokij/dokuwiki-plugin-markdownextra
• https://bitbucket.org/jpulakka/markdownextra-plugin-for-dokuwiki

If the page name ends with .md suffix, it gets automatically parsed using PHP Markdown Extra. To use that markup in other pages, the content must be embedded in a markdown block. For example:

<markdown>
Header 1
========

~~~
some code
~~~

Paragraph

Header 2
--------

- A
- simple
- list

1. And
2. numbered
3. list

Quite intuitive? *emphasis*, **strong**, etc.
</markdown>

For syntax, refer to http://michelf.com/projects/php-markdown/extra/

This feature was added in version 2013-01-02, it's turned off by default. You may turn it on in dokuwiki config page.

I love this markdown extra plugin, the best feature is .md suffix. And I love tag plugin too, but I can't use it with page with .md suffix as {{tag>tat1 tag2 tag3}} syntax will not work within <markdown></markdown>. So I added this front matter feature.

Front matter is a text block at the top of dokuwiki page with .md suffix. It begins and ends with '---'. Looks like this:

---
{{tag>test}}
---

Content between --- will be placed outside <markdown></markdown> so it will be accessible by tag plugin or any other plugin.

• It would be very good improvement to render standard wiki links properly to represent them clearly and to work with link plugins.
• It would be nice to have GeShi support in between the markdown tags. Support for the <code language></code> tags * Updating the PHP Markdown lib to 1.2.7 will enable ~~~ language code blocks, but still have to figure out how to hook into GeShi or other syntax highlighter This is not merged in but can be accessed from here: https://github.com/ajwillia-ms/dokuwiki-plugin-markdownextra
• Could the plugin parse files that have the .markdown extension too? This is becoming widely used.
• Can section editing be supported?
  • Doesn't seem straightforward as DokuWiki output is totally different from PHP Markdown output (e.g. the sectionedit and level1, level2 divs)
• Could one of the editors like:markitup or even Meltdown be supported? (edit: Meltdown is implemented)
• Could we had a <dk></dk> tag to tell the markdown parser to ignore this part which would be processed by dokuwiki parser or plugins. or else could we use the --- front-matter several times and not only on top of the document. It’s like a <nomarkdown></nomarkdown> tag for markdown files.

• it seems backlinks and headers parsers dont work with this plugins — no toc, no „page-name-from-first-header“, no backlinks and no orphan pages
  • Should work now (2012-11-25), thanks to Jiang Le.
• The table of contents is shown only the first time the page is viewed after a clear cache (e.g. with ?purge=true it's always shown). Any subsequent reload of the page shows no table of contents.
  • I think this should be a cache related problem. Adding ~~NOCACHE~~ to source of the page should fix that. However I don't have this problem with my installation.
  • ~~NOCACHE~~ does work around the problem, but I am interested in a solution. How can I find out why this is happening? This is a somewhat minimal install. The problem still exists even when markdownextra is the only enabled plugin. Could some dokuwiki settings cause the problem?
  • Not sure what cause this. Maybe something in TOC metadata makes the dokuwiki core unhappy. Please report this bug via the „Report bugs“ link on this plugin page, include your dokuwiki version, server os version, php & webserver version, and a sample page with the bug report.
  • Fixed. Please remove the markdown extra plugin and install it again with this url https://github.com/naokij/dokuwiki-plugin-markdownextra/tarball/master

I uploaded a file with .md extension into the pages directory, but it is not listed in the wiki. What else do I have to do?
The file must have both .md and .txt extensions like something.md.txt. Dokuwiki needs the .txt to recognise the file as a page, while the plugin needs the .md to recognise the syntax. Filenames should also be lowercase and with no spaces. If you're using DokuWiki's web interface, just name your page something.md, but the file will actually be named something.md.txt.

How do I put links in .md pages to other sections of the wiki?
Like this: [this is a link](?id=anotherpage.md) or [this is a link](./anotherpage.md)

But what about the „normal“ link style [[anotherpage]]?
The „normal“ link style is not Markdown syntax, so you have to choose: use Markdown, or not.

How do I generate a table of contents on top of the page?
Should work now (2012-11-25), thanks to Jiang Le.

How do I embed an image from the wiki?

![alt text](lib/exe/fetch.php?media=namespace:image.png)

If you have enabled URL rewriting mode 1 (webserver), you can use _media/ as a shorthand for lib/exe/fetch.php?media=, so you only need to type ![alt text](_media/namespace/image.png)

If you want to link the image (e.g. to the DokuWiki details page), you have to wrap the entire image markup in a link:

[![alt text](lib/exe/fetch.php?media=namespace:image.png)](lib/exe/detail.php?media=namespace:image.png)

with URL rewriting mode 1, the shorter form is [![alt text](_media/namespace/image.png)](_detail/namespace/image.png)

The included version of PHP Markdown in this plugin is 1.2.8 from November 29, 2013. This is the latest version and supports a few new features like classes and IDs for headers, images, links and fenced code blocks; multiple references to the same footnote; as well as bugfixes.

If there are future releases, to update, just replace markdown.php in lib/plugins/markdownextra with the new version (though likely there will not be a new release). Make sure to use classic version PHP Markdown Extra x.x.x, not PHP Markdown Lib.