Markdown WikiLink Extension achinghead.com

Summary

Markdown WikiLink is an extension to the Python implementation of Markdown that adds WikiLinks. Specifically, any CamelCase word is converted to a link.

Get the Code

You can view or download version 0.5 or, if you prefer leading edge, the latest from trunk.

Previous Versions

Dependencies

Note: If you are not using Markdown 1.6 or later, I would suggest using Version 0.3 of the WikiLink Extention. See the README.txt file for documentation relevant to that version.

Note: There is known incompatibility with Markdown 1.6b. See the bug report and patch for details.

License

The Markdown WikiLink Extension is licensed under the BSD License.

Syntax

A CamelCase word is defined as a uppercase letter followed by any number of lower case letters (including dashes [-] or underscores [_]) repeated two or more times. Therefore

CamelCase

Would produce the following html:

<a href="/CamelCaseWord/" class="wikilink">CamelCase</a>

Note that wikilinks are automatically assigned class="wikilink" making it easy to style wikilinks differently from other links on a page if one so desires. See below for ways to alter the class.

You should also note that when a underscore [_] is used, the underscore is converted to a space in the label but not in the link. Perhaps an example would illustrate this best:

Wiki_Link

Becomes

<a href="/Wiki_Link/" class="wikilink">Wiki Link</a>

There may be occasions when you what to use a CamelCase word but not have it converted into a link. You can escape the word by adding a backslash [\] to the beginning like so:

This will not become a \WikiLink.

That will simply output:

This will not become a WikiLink.

Usage

From the Python interpreter:

>>> import markdown
>>> text = "Some text with a WikiLink."
>>> md = markdown.markdown(text, ['wikilink'])
>>> html = str(md)

To use with other extensions, just add them to the list, like this:

>>> md = markdown.markdown(text, ['wikilink', 'footnotes'])

WikiLink can also be called from the command line using Markdown's -x parameter, like so:

python markdown.py -x wikilink source.txt > output.html

Customizing the Output

The default behavior is to point each link to the document root of the current domain and close with a trailing slash. Additionally, each link is assigned to the html class wikilink. This may not always be desirable. Therefore, one can customize that behavior within Python code. Three settings are provided to change the default behavior:

base_url: String to append to beginning of URL.

Default: '/'
end_url: String to append to end of URL.

Default: '/'
html_class: CSS hook. Leave blank for none.

Default: 'wikilink'

For an example, let us suppose links should always point to the subdirectory /wiki/ and end with .html

>>> md = markdown.markdown(text, 
...     ['wikilink(base_url=/wiki/,end_url=.html)']
... )

The above would result in the following link for WikiLink.

<a href="/wiki/WikiLink.html" class="wikilink">WikiLink</a>

The option is also provided to change or remove the class attribute.

>>> md = markdown.markdown(text, 
...     ['wikilink(base_url=myclass)']
... )

Would cause all wikilinks to be assigned to the class myclass.

<a href="/WikiLink/" class="myclass">WikiLink</a>

The same options can be used on the command line as well:

python markdown.py -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt

Some may prefer the more complex format when calling the Markdown class directly:

>>> md = markdown.Markdown(text, 
...     extensions = ['wikilink'], 
...     extension_configs = {'wikilink': [
...                                 ('base_url', 'http://example.com/'), 
...                                 ('end_url', '.html'),
...                                 ('html_class', '') ]},
...     encoding='utf8',
...     safe_mode = True)

Using with Meta-Data

The WikiLink Extension also supports the Meta-Data Extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are:

wiki_base_url
wiki_end_url
wiki_html_class

When used, the meta-data will override the settings provided through the
extension_configs interface.

This document:

wiki_base_url: http://example.com/
wiki_end_url:  .html
wiki_html_class: 

A WikiLink in the first paragraph.

would result in the following output (notice the blank wiki_html_class):

<p>A <a href="http://example.com/WikiLink.html">WikiLink</a> in the first paragraph.
</p>

Misc

For more info you may want to read my blog posts related to markdown. The Python Markdown mailing list should be of assistance should you need help getting things to work. Bug reports and improvements are welcome (waylan [AT] gmail [DOT] com).

achinghead.com