<!DOCTYPE html>
<html>
<head>
<meta charset=utf-8>
<title>Wikilinks Extension — Python Markdown</title>
<link rel="stylesheet" href="../default.css" type="text/css">
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../siteindex.html" title="General Index">index</a></li>
<li class="right">
<a href="api.html" title="Extension API"
accesskey="N">next</a> |</li>
<li class="right">
<a href="toc.html" title="Table of Contents Extension"
accesskey="P">previous</a> |</li>
<li><img src="../py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python Markdown v2.3.1 documentation</a> »</li>
<li><a href="index.html">Extensions</a> »</li>
<li><a href="wikilinks.html">Wikilinks Extension</a> »</li>
</ul>
</div> <!-- .related -->
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<h1 id="wikilinks">WikiLinks</h1>
<h2 id="summary">Summary</h2>
<p>An extension to Python-Markdown that adds <a href="http://en.wikipedia.org/wiki/Wikilink">WikiLinks</a>. Specifically, any
<code>[[bracketed]]</code> word is converted to a link.</p>
<p>This extension has been included in the Markdown library since 2.0.</p>
<h2 id="syntax">Syntax</h2>
<p>A <code>[[bracketed]]</code> word is any combination of upper or lower case letters,
number, dashes, underscores and spaces surrounded by double brackets. Therefore </p>
<pre><code>[[Bracketed]]
</code></pre>
<p>Would produce the following html:</p>
<pre><code><a href="/Bracketed/" class="wikilink">Bracketed</a>
</code></pre>
<p>Note that wikilinks are automatically assigned <code>class="wikilink"</code> 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.</p>
<p>You should also note that when a space is used, the space is converted to an
underscore in the link but left as-is in the label. Perhaps an example
would illustrate this best:</p>
<pre><code>[[Wiki Link]]
</code></pre>
<p>Becomes</p>
<pre><code><a href="/Wiki_Link/" class="wikilink">Wiki Link</a>
</code></pre>
<h2 id="usage">Usage</h2>
<p>From the Python interpreter:</p>
<pre><code>>>> text = "Some text with a [[WikiLink]]."
>>> html = markdown.markdown(text, ['wikilink'])
</code></pre>
<p>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 <code>wikilink</code>. This may not always be desirable. Therefore, one can
customize that behavior within Python code. Four settings are provided to
change the default behavior:</p>
<ol>
<li>
<p><strong>base_url</strong>: String to append to beginning of URL. </p>
<p>Default: <code>'/'</code></p>
</li>
<li>
<p><strong>end_url</strong>: String to append to end of URL.</p>
<p>Default: <code>'/'</code></p>
</li>
<li>
<p><strong>html_class</strong>: CSS hook. Leave blank for none.</p>
<p>Default: <code>'wikilink'</code></p>
</li>
<li>
<p><strong>build_url</strong>: Callable which formats the URL from it's parts.</p>
</li>
</ol>
<p>For an example, let us suppose links should always point to the subdirectory
<code>/wiki/</code> and end with <code>.html</code></p>
<pre><code>>>> html = markdown.markdown(text,
... ['wikilink(base_url=/wiki/,end_url=.html)']
... )
</code></pre>
<p>The above would result in the following link for <code>[[WikiLink]]</code>.</p>
<pre><code><a href="/wiki/WikiLink.html" class="wikilink">WikiLink</a>
</code></pre>
<p>If you want to do more that just alter the base and/or end of the URL, you
could also pass in a callable which must accept three arguments (<code>label</code>,
<code>base</code>, and <code>end</code>). The callable must return the URL in it's entirety.</p>
<pre><code>def my_url_builder(label, base, end):
# do stuff
return url
md = markdown.Markdown(
extensions=['wikilinks],
extension_configs={'wikilinks' : [('build_url', my_url_builder)]}
)
</code></pre>
<p>The option is also provided to change or remove the class attribute.</p>
<pre><code>>>> html = markdown.markdown(text,
... ['wikilink(html_class=myclass)']
... )
</code></pre>
<p>Would cause all wikilinks to be assigned to the class <code>myclass</code>.</p>
<pre><code><a href="/WikiLink/" class="myclass">WikiLink</a>
</code></pre>
<p>The same options can be used on the command line as well:</p>
<pre><code>python -m markdown -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt
</code></pre>
<p>Some may prefer the more complex format when calling the <code>Markdown</code> class directly:</p>
<pre><code>>>> md = markdown.Markdown(
... extensions = ['wikilink'],
... extension_configs = {'wikilink': [
... ('base_url', 'http://example.com/'),
... ('end_url', '.html'),
... ('html_class', '') ]},
... safe_mode = True
... )
>>> html = md.convert(text)
</code></pre>
<h2 id="using-with-meta-data">Using with Meta-Data</h2>
<p>The WikiLink Extension also supports the <a href="meta_data.html">Meta-Data</a> Extension.
Please see the documentation for that extension for specifics. The supported
meta-data keywords are:</p>
<ul>
<li><code>wiki_base_url</code></li>
<li><code>wiki_end_url</code></li>
<li><code>wiki_html_class</code></li>
</ul>
<p>When used, the meta-data will override the settings provided through the
<code>extension_configs</code> interface. </p>
<p>This document:</p>
<pre><code>wiki_base_url: http://example.com/
wiki_end_url: .html
wiki_html_class:
A [[WikiLink]] in the first paragraph.
</code></pre>
<p>would result in the following output (notice the blank <code>wiki_html_class</code>):</p>
<pre><code><p>A <a href="http://example.com/WikiLink.html">WikiLink</a> in the first paragraph.</p>
</code></pre>
</div> <!-- .body -->
</div> <!-- .bodywrapper -->
</div> <!-- .documentwrapper -->
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3>Table Of Contents</h3>
<div class="toc">
<ul>
<li><a href="#wikilinks">WikiLinks</a><ul>
<li><a href="#summary">Summary</a></li>
<li><a href="#syntax">Syntax</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#using-with-meta-data">Using with Meta-Data</a></li>
</ul>
</li>
</ul>
</div>
<h4>Previous topic</h4>
<p class="topless"><a href="toc.html"
title="previous chapter">Table of Contents Extension</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="api.html"
title="next chapter">Extension API</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="https://github.com/waylan/Python-Markdown/issues"
>Report a Bug</a></li>
<li><a href="wikilinks.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div> <!-- .sphinxsidebarwrapper -->
</div> <!-- .sphinxsidebar -->
<div class="clearer"></div>
</div> <!-- .document -->
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../siteindex.html" title="General Index">index</a></li>
<li class="right">
<a href="api.html" title="Extension API"
accesskey="N">next</a> |</li>
<li class="right">
<a href="toc.html" title="Table of Contents Extension"
accesskey="P">previous</a> |</li>
<li><img src="../py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python Markdown v2.3.1 documentation</a> »</li>
<li><a href="index.html">Extensions</a> »</li>
<li><a href="wikilinks.html">Wikilinks Extension</a> »</li>
</ul>
</div> <!-- .related -->
<div class="footer">© 2010-2012 Python Markdown Project</div>
</body>
</html>
