====== MarkdownExtra Plugin ===== ---- plugin ---- description: Parses PHP Markdown Extra blocks author : Joonas Pulakka, Jiang Le email : joonas.pulakka@iki.fi, smartynaoki@gmail.com type : syntax lastupdate : 2016-02-02 compatible : 2012-10-13 "Adora Belle" depends : conflicts : similar : markdowku, markdown tags : formatting, markdown, markup_language downloadurl: https://github.com/naokij/dokuwiki-plugin-markdownextra/tarball/master sourcerepo : https://github.com/naokij/dokuwiki-plugin-markdownextra/ bugtracker : https://github.com/naokij/dokuwiki-plugin-markdownextra/issues ---- ===== Download and Installation ===== Search and install the plugin using the [[plugin:extension|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 ===== Usage ===== 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: Header 1 ======== ~~~ some code ~~~ Paragraph Header 2 -------- - A - simple - list 1. And 2. numbered 3. list Quite intuitive? *emphasis*, **strong**, etc. For syntax, refer to http://michelf.com/projects/php-markdown/extra/ ==== Front matter ==== 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 [[:plugin:tag|tag plugin]] too, but I can't use it with page with ''.md'' suffix as %%{{tag>tat1 tag2 tag3}}%% syntax will not work within ''''. 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 '''' so it will be accessible by [[:plugin:tag|tag plugin]] or any other plugin. ===== Discussion ===== ==== Feature requests ==== * 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 '''' tags * Updating the PHP Markdown lib to 1.2.7 will enable ''~~~ language'' [[http://michelf.ca/projects/php-markdown/extra/#fenced-code-blocks|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:[[http://markitup.jaysalvat.com/|markitup]] or even [[https://github.com/iphands/Meltdown|Meltdown]] be supported? (edit: Meltdown is implemented) * Could we had a '''' 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 '''' tag for markdown files. ==== Bugs ==== * 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 ==== FAQ / Support ==== **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 [[:rewrite|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)'' ==== Updating to latest PHP Markdown ==== The included version of [[http://michelf.ca/projects/php-markdown/|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.