Markdown in Python: WikiLinks

Anonymous users must enter captcha below.

Don't put anything here

Page Parameters

Page Name (for URL)

Page Title

Don't put anything here

Show Advanced Options

Page Content

###Summary

An extension to Python-Markdown that adds WikiLinks. Specifically, any [CamelCase][] word is converted to a link.

[CamelCase]: http://en.wikipedia.org/wiki/CamelCase "Wikipedia definition"

###Get the Code

The code is currently available in the Python-Markdown Git [repository][] and will likely be included in the next release.

[repository]: http://gitorious.org/projects/python-markdown/repos/mainline/blobs/master/mdx_wikilink.py

####Dependencies

* [Python 2.3+](http://python.org)
* [Markdown 1.7+](http://www.freewisdom.org/projects/python-markdown/)

####License
The Markdown WikiLink Extension is licensed under the [BSD](http://www.opensource.org/licenses/bsd-license.php) 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

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."
    >>> html = markdown.markdown(text, ['wikilink'])

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

>>> html = 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:

1. **base_url**: String to append to beginning of URL.

Default: `'/'`

2. **end_url**: String to append to end of URL.

Default: `'/'`

3. **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`

>>> html = 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.

>>> html = 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( 
    ...     extensions = ['wikilink'], 
    ...     extension_configs = {'wikilink': [
    ...                                 ('base_url', 'http://example.com/'), 
    ...                                 ('end_url', '.html'),
    ...                                 ('html_class', '') ]},
    ...     encoding='utf8',
    ...     safe_mode = True
    ... )
    >>> html = md.convert(text)

###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>

About this Edit

Minor Edit

Edit Summary

Don't put anything here