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