Wiki Markdown

04/02/2007 12:15:37

I like using OddMuse as the software behind my wiki sites, but I prefer to use Markdown as the syntax for my editing. It is easier (for me) to remember, and you can then use the same text for your Wiki, a weblog (running a Markdown plugin), or as input for my MultiMarkdown software.

Unfortunately, there are shared elements between the default Oddmuse syntax, and MarkdownSyntax. Fortunately, Alex Schröeder has written a Markdown Extension that overrides the default syntax and allows you to use Markdown within an Oddmuse wiki.

The official Markdown Extension is not supported by Alex, but I have submitted my improvements and will continue to do so.

Download the latest version:

markdown.pl

In order to add some additional features I wanted in Markdown, and that are definitely useful in Oddmuse, I recommend using MultiMarkdown as the parsing engine for the Markdown Extension.

In the meantime, this site is run using Markdown (well, MultiMarkdown)- feel free to see how it works.

IMPORTANT NOTE

I think there is a bug in QuoteHTML in the Oddmuse source.

The original line is:

$html =~ s/&([#a-zA-Z0-9]+);/&$1;/g;  # Allow character references

I believe the proper line should be:

$html =~ s/&(#[a-zA-Z0-9]+);/&$1;/g;  # Allow character references

This was causing issues with the markdown plugin and code blocks. The fixed version seems to work properly..

In order to get the Markdown Extension to work properly, you should make this change to your copy of the Oddmuse source code, until Alex fixes the official code, or someone shows me how I am mistaken, and then I need to try to repair the Markdown Extension.

Known Bugs

Not really a bug, but by using this extension, you effectively disable other plugins that parse the text and apply various rules. This is likely somewhat intentional, but fairly necessary, and required based on the way that OddMuse processes text for markup.
Multimarkdown has trouble properly parsing blockquotes within code sections

Markdown Extension Compatibility

Modules can now be modified such that they are compatible with the Markdown extension. For example, the [[FlickrGallery Module]] uses the <FlickrSet:#####> command to do it’s thing. As noted above, the Markdown extension prevents other rules from being run. Instead, you can reformat the rules so that they can be added to @MyMarkdownRules rather than @MyRules. Check out the [[FlickrGallery Module]] to see how this works.

Things To Do

I am toying with changing the [[Free Links]] syntax. It is different from the syntax from all other Markdown links, which is strange, but perhaps a good thing. Comments on this would be helpful.

Outside Implications

Changes that have to be made to other bits of Oddmuse on each site to use Markdown:

Need to change commentcount extension to use ### instead of ===, and it needs to be renamed to load after markdown
<journal> tags can only be used at the beginning of a page, and other text on the page does not get processed by Markdown - there may be an easy way around this, but I have not looked too hard for it.

Possible things to do

consider supporting [[URL Abbreviations]], but I think this would further take away from the compatibility benefit of using Markdown (it’s bad enough adding support for WikiWords)

Resolved

Because the use of Markdown bypasses the built-in parsing in Oddmuse, raw html can be passed through unprocessed. This potentially allows attackers to include exploitive code in wiki pages… This needs to be stopped. (Without screwing up other processing)
Fix issue with WikiWords within [[Free Links]]
image: matching doesn’t work with _ in page name
need to support matching download: tags
Update the comment signature feature to save URL in a Markdown compatible format

Version History

1.37 - Fix more bugs that got introduced in this strange version hiccup…
1.35–1.36 - Something strange happened, and some versions got deleted. Not sure how. Anyways, added back SmartyPants support, and the MyMarkdownRules feature that somehow got deleted. Also, now defaults to looking for MultiMarkdown.pl
1.34 - Fix bug where parsing metadata screws up pages with a colon or link in first line
1.33 - Continue to fix bug with ‘<’ around reference-style links
1.32 - Fix bug with ‘<’ around reference-style links
1.31 - Fix bug with escaping WikiWords
1.30 - fix handling of Wiki Words within Markdown links
1.29 - disable use of metadata
1.28 - revert to original QuoteHtml behavior, after patching bug in Oddmuse’s QuoteHtml routine

Require a WikiWord to be preceded by whitespace to prevent over-eager matching
1.27 - Fix bug when using WikiLinks with underlines(spaces)
1.26 - Fix bug when calling _UnescapeSpecialChars()
1.25 - Fix problem with linebreaks
1.24 - Added detection for MultiMarkdown to allow footnotes
1.23 - Added ability for other modules to patch in and provide rules