README.md
1Dokuwiki Commonmark Plugin
2===========================
3
4## Description
5This is another plugin for parsing Commonmark / Markdown document in Dokuwiki.
6
7While there are many Markdown plugins (for example, [markdownu](https://www.dokuwiki.org/plugin:markdowku), [mdpage](https://www.dokuwiki.org/plugin:mdpage)) available, this plugin processes Markdown text in different approach:
8
91. check that Markdown indicator ('\<!DOCTYPE markdown\>') is included on the document
102. if exists, parses entire document and renders to DW syntax
113. After pre-rendering, passes the result to DW parser and process as usual
12
13If you want to parse all DW pages as Commonmark without specific doctype, you can enable `force_commonmark` option on config. But this action may conflit with existing document of DW markup, so please use it carefully.
14
15## Compatibility
16Commonmark plugin aims for complete compatiblity of Markdown in Dokuwiki. Most Markdown syntax have corresponding DW syntax, so it will work without problem; but in some cases, Markdown syntax do not matches DW specification one-by-one, or vice versa. Here is a list of known ambiguities between Commonmark and Dokuwiki, and its implements in the plugin:
17
18- Since the release of "Jack Jackrun", DW have [completely disabled](https://www.dokuwiki.org/faq:html) embedding HTML code. [HTML blocks](https://spec.commonmark.org/0.30/#html-blocks) will be passed as-is, unless enabling [htmlok plugin](https://www.dokuwiki.org/plugin:htmlok); but it is recommended to use it in limited environments.
19- If you have enabled htmlok plugin, adding `html` as [info string](https://spec.commonmark.org/0.28/#info-string) in [Fenced code blocks](https://spec.commonmark.org/0.30/#fenced-code-blocks) will parse HTML code inside the block to DW's [\<HTML\>](https://www.dokuwiki.org/wiki:syntax#embedding_html_and_php) block; In case of `nowiki`, `<nowiki>` syntax will be parsed; if `dokuwiki`, raw DW code will be passed. For example:
20
21````
22```dokuwiki
23<sub>subscript</sub>
24```
25````
26
27Commonmark plugin would conflit with other markdown-related plugins, including [Mdpage](https://www.dokuwiki.org/plugin:mdpage).
28
29Due to the plugin's mechanism, section edit button recognize the section as broken snippet rather than expected; it can be fixed if you enable `fix_secedit` option on config. Note that you must delete cache (ex: `?purge=true`) to work this feature correctly.
30
31## License
32
33- icons: Apache License from https://www.iconbolt.com/
34