Debian Codegraph @

docs/extensions/wikilinks.md

raw
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 ```