1WikiLinks 2========= 3 4Summary 5------- 6 7An extension to Python-Markdown that adds [WikiLinks][]. Specifically, any 8``[[bracketed]]`` word is converted to a link. 9 10[WikiLinks]: http://en.wikipedia.org/wiki/Wikilink 11 12This extension has been included in the Markdown library since 2.0. 13 14Syntax 15------ 16 17A ``[[bracketed]]`` word is any combination of upper or lower case letters, 18number, dashes, underscores and spaces surrounded by double brackets. Therefore 19 20 [[Bracketed]] 21 22Would produce the following html: 23 24 <a href="/Bracketed/" class="wikilink">Bracketed</a> 25 26Note that wikilinks are automatically assigned `class="wikilink"` making it 27easy to style wikilinks differently from other links on a page if one so 28desires. See below for ways to alter the class. 29 30You should also note that when a space is used, the space is converted to an 31underscore in the link but left as-is in the label. Perhaps an example 32would illustrate this best: 33 34 [[Wiki Link]] 35 36Becomes 37 38 <a href="/Wiki_Link/" class="wikilink">Wiki Link</a> 39 40Usage 41----- 42 43From the Python interpreter: 44 45 >>> text = "Some text with a [[WikiLink]]." 46 >>> html = markdown.markdown(text, ['wikilink']) 47 48The default behavior is to point each link to the document root of the current 49domain and close with a trailing slash. Additionally, each link is assigned to 50the html class `wikilink`. This may not always be desirable. Therefore, one can 51customize that behavior within Python code. Three settings are provided to 52change the default behavior: 53 541. **base_url**: String to append to beginning of URL. 55 56 Default: `'/'` 57 582. **end_url**: String to append to end of URL. 59 60 Default: `'/'` 61 623. **html_class**: CSS hook. Leave blank for none. 63 64 Default: `'wikilink'` 65 664. **build_url**: Callable which formats the URL from it's parts. 67 68For an example, let us suppose links should always point to the subdirectory 69`/wiki/` and end with `.html` 70 71 >>> html = markdown.markdown(text, 72 ... ['wikilink(base_url=/wiki/,end_url=.html)'] 73 ... ) 74 75The above would result in the following link for `[[WikiLink]]`. 76 77 <a href="/wiki/WikiLink.html" class="wikilink">WikiLink</a> 78 79If you want to do more that just alter the base and/or end of the URL, you 80could also pass in a callable which must accept three arguments (``label``, 81``base``, and ``end``). The callable must return the URL in it's entirety. 82 83 def my_url_builder(label, base, end): 84 # do stuff 85 return url 86 87 md = markdown.Markdown( 88 extensions=['wikilinks], 89 extension_configs={'wikilinks' : [('build_url', my_url_builder)]} 90 ) 91 92 93The option is also provided to change or remove the class attribute. 94 95 >>> html = markdown.markdown(text, 96 ... ['wikilink(base_url=myclass)'] 97 ... ) 98 99Would cause all wikilinks to be assigned to the class `myclass`. 100 101 <a href="/WikiLink/" class="myclass">WikiLink</a> 102 103The same options can be used on the command line as well: 104 105 python markdown.py -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt 106 107Some may prefer the more complex format when calling the `Markdown` class directly: 108 109 >>> md = markdown.Markdown( 110 ... extensions = ['wikilink'], 111 ... extension_configs = {'wikilink': [ 112 ... ('base_url', 'http://example.com/'), 113 ... ('end_url', '.html'), 114 ... ('html_class', '') ]}, 115 ... safe_mode = True 116 ... ) 117 >>> html = md.convert(text) 118 119Using with Meta-Data 120-------------------- 121 122The WikiLink Extension also supports the [[Meta-Data]] Extension. Please see 123the documentation for that extension for specifics. The supported meta-data 124keywords are: 125 126* `wiki_base_url` 127* `wiki_end_url` 128* `wiki_html_class` 129 130When used, the meta-data will override the settings provided through the 131`extension_configs` interface. 132 133This document: 134 135 wiki_base_url: http://example.com/ 136 wiki_end_url: .html 137 wiki_html_class: 138 139 A [[WikiLink]] in the first paragraph. 140 141would result in the following output (notice the blank `wiki_html_class`): 142 143 <p>A <a href="http://example.com/WikiLink.html">WikiLink</a> in the first paragraph.</p> 144 145