| 1 |
title: WikiLinks Extension |
| 2 |
|
| 3 |
# WikiLinks |
| 4 |
|
| 5 |
## Summary |
| 6 |
|
| 7 |
The WikiLinks extension adds support for [WikiLinks][]. Specifically, any |
| 8 |
``[[bracketed]]`` word is converted to a link. |
| 9 |
|
| 10 |
This extension is included in the standard Markdown library. |
| 11 |
|
| 12 |
[WikiLinks]: https://en.wikipedia.org/wiki/Wikilink |
| 13 |
|
| 14 |
## Syntax |
| 15 |
|
| 16 |
A ``[[bracketed]]`` word is any combination of upper or lower case letters, |
| 17 |
number, dashes, underscores and spaces surrounded by double brackets. Therefore |
| 18 |
|
| 19 |
```md |
| 20 |
[[Bracketed]] |
| 21 |
``` |
| 22 |
|
| 23 |
would produce the following HTML: |
| 24 |
|
| 25 |
```html |
| 26 |
<a href="/Bracketed/" class="wikilink">Bracketed</a> |
| 27 |
``` |
| 28 |
|
| 29 |
Note that WikiLinks are automatically assigned `class="wikilink"` making it |
| 30 |
easy to style WikiLinks differently from other links on a page if one so |
| 31 |
desires. See below for ways to alter the class. |
| 32 |
|
| 33 |
Also note that when a space is used, the space is converted to an underscore in |
| 34 |
the link but left as-is in the label. Perhaps an example would illustrate this |
| 35 |
best: |
| 36 |
|
| 37 |
```md |
| 38 |
[[Wiki Link]] |
| 39 |
``` |
| 40 |
|
| 41 |
becomes |
| 42 |
|
| 43 |
```html |
| 44 |
<a href="/Wiki_Link/" class="wikilink">Wiki Link</a> |
| 45 |
``` |
| 46 |
|
| 47 |
## Usage |
| 48 |
|
| 49 |
See [Extensions](index.md) for general extension usage. Use `wikilinks` as the |
| 50 |
name of the extension. |
| 51 |
|
| 52 |
See the [Library Reference](../reference.md#extensions) for information about |
| 53 |
configuring extensions. |
| 54 |
|
| 55 |
The default behavior is to point each link to the document root of the current |
| 56 |
domain and close with a trailing slash. Additionally, each link is assigned to |
| 57 |
the HTML class `wikilink`. |
| 58 |
|
| 59 |
The 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 |
|
| 75 |
A trivial example: |
| 76 |
|
| 77 |
```python |
| 78 |
markdown.markdown(some_text, extensions=['wikilinks']) |
| 79 |
``` |
| 80 |
|
| 81 |
### Examples |
| 82 |
|
| 83 |
For 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 |
|
| 93 |
The above would result in the following link for `[[WikiLink]]`. |
| 94 |
|
| 95 |
```html |
| 96 |
<a href="/wiki/WikiLink.html" class="wikilink">WikiLink</a> |
| 97 |
``` |
| 98 |
|
| 99 |
If you want to do more that just alter the base and/or end of the URL, you |
| 100 |
could 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 |
|
| 113 |
The 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 |
|
| 121 |
Would 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 |
|
| 129 |
The WikiLink extension also supports the [Meta-Data](meta_data.md) extension. |
| 130 |
Please see the documentation for that extension for specifics. The supported |
| 131 |
meta-data keywords are: |
| 132 |
|
| 133 |
* `wiki_base_url` |
| 134 |
* `wiki_end_url` |
| 135 |
* `wiki_html_class` |
| 136 |
|
| 137 |
When used, the meta-data will override the settings provided through the |
| 138 |
`extension_configs` interface. |
| 139 |
|
| 140 |
This document: |
| 141 |
|
| 142 |
```md |
| 143 |
wiki_base_url: http://example.com/ |
| 144 |
wiki_end_url: .html |
| 145 |
wiki_html_class: |
| 146 |
|
| 147 |
A [[WikiLink]] in the first paragraph. |
| 148 |
``` |
| 149 |
|
| 150 |
would 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 |
``` |