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