A wikilink extension for Python Markdown
Project description
Converts wikilinks ([[wikilink]]
) to relative links. Absolute links are kept as is (with an automatic label made from the file path part in the URL if label is not given explicitly).
You should not use markdown.extensions.wikilinks along with this one. This extension is designed to provide the functionalities of markdown.extensions.wikilinks along with some extra features. Choose either one.
Install
pip install mdx_wikilink_plus
Wikilink syntax
The geneal formats are:
- Without explicit label:
[[wikilink]]
- With explicit label:
[[ link | label ]]
Usage
text = "[[wikilink]]"
md = markdown.Markdown(extensions=['mdx_wikilink_plus'])
html = md.convert(text)
Quick examples
[[/path/to/file-name]]
will become:
<p><a class="wikilink" href="/path/to/file-name">File Name</a></p>
[[https://www.example.com/example-tutorial]]
will become:
<p><a class="wikilink" href="https://www.example.com/example-tutorial">Example Tutorial</a></p>
and [[https://www.example.com/?a=b&b=c]]
will become:
<p><a class="wikilink" href="https://www.example.com/?a=b&b=c">www.example.com</a></p>
Configuration
The configuration options are:
Config param | Default | Details |
---|---|---|
base_url | '' |
Prepended to the file_path part of the URL. A / at the end of the base_url will be handled intelligently. |
end_url | '' |
Appended to the file_path part of the URL. If end_url is given (non-empty), then any / at the end of the file_path part in the URL is removed. If the end_url matches the extension of the file_path part, it will be ignored, for example, if end_url is .html and the wikilink provided is [[/path/to/myfile.html]] , then the URL will be /path/to/myfile.html not /path/to/myfile.html.html . |
url_whitespace | '-' |
Replace all whitespace in the file_path path with this character (string) when building the URL. |
label_case | 'titlecase' |
Choose case of the label. Available options: titlecase, capitalize, none. Capitalize will capitalize the first character only. |
html_class | 'wikilink' |
Set custom HTML classes on the anchor tag. It does not add classes rather it resets any previously set value. |
build_url | mdx_wikilink_plus.build_url |
A callable that returns the URL string. Default build_url callable |
None of the configs apply on absolute URLs except html_class and build_url. (Yes, label_case won't work either)
Configuration through meta data
Configuration can also be passed through metadata (markdown.extensions.meta).
We recognize the following template:
wiki_base_url: /static/
wiki_end_url:
wiki_url_whitespace: _
wiki_label_case: capitalize
wiki_html_class: wikilink
The first line of the document
An example with configuration:
md_configs = {
'mdx_wikilink_plus': {
'base_url': '/static',
'end_url': '.html',
'url_whitespace': '-',
'label_case': 'titlecase',
'html_class': 'a-custom-class',
#'build_url': build_url, # A callable
# all of the above config params are optional
},
}
text = """
[[/path/to/file-name]]
[[/path/to/file name/?a=b&b=c]]
"""
md = markdown.Markdown(extensions=['mdx_wikilink_plus'], extension_configs=md_configs)
print(md.convert(text))
The output will be:
<p><a class="a-custom-class" href="/static/path/to/file-name.html">File Name</a></p>
<p><a class="a-custom-class" href="/static/path/to/file-name.html?a=b&b=c">File Name</a></p>
!!! info
end_url
is added at the end of the file-path part in the URL.
More examples
Our test markdown:
[[wikilink]] `[[wikilink]]`
[[/path/to/file name]]
[[/path/to/file_name]]
[[/path/to/file-name]]
[[/path/to/file name/?a=b&b=c]]
[[/path/to/file name.html]]
[[/path/to/file name.html?a=b&b=c]]
[[https://www.example.com/?]]
[[https://www.example.com/?a=b&b=c]]
[[https://www.example.com/example-tutorial]]
[[https://www.example.com/example-tutorial | Example Tutorial]]
Output without any config
<p><a class="wikilink" href="wikilink">Wikilink</a> <code>[[wikilink]]</code></p>
<p><a class="wikilink" href="/path/to/file-name">File Name</a></p>
<p><a class="wikilink" href="/path/to/file_name">File Name</a></p>
<p><a class="wikilink" href="/path/to/file-name">File Name</a></p>
<p><a class="wikilink" href="/path/to/file-name/?a=b&b=c">File Name</a></p>
<p><a class="wikilink" href="/path/to/file-name.html">File Name</a></p>
<p><a class="wikilink" href="/path/to/file-name.html?a=b&b=c">File Name</a></p>
<p><a class="wikilink" href="https://www.example.com/">www.example.com</a></p>
<p><a class="wikilink" href="https://www.example.com/?a=b&b=c">www.example.com</a></p>
<p><a class="wikilink" href="https://www.example.com/example-tutorial">Example Tutorial</a></p>
<p><a class="wikilink" href="https://www.example.com/example-tutorial">Example Tutorial</a></p>
With a config
With the configuration
'mdx_wikilink_plus': {
'base_url': '/static',
'end_url': '.html',
'url_whitespace': '-',
'label_case': 'titlecase',
'html_class': 'a-custom-class',
},
the output will be:
<p><a class="a-custom-class" href="/static/wikilink.html">Wikilink</a> <code>[[wikilink]]</code></p>
<p><a class="a-custom-class" href="/static/path/to/file-name.html">File Name</a></p>
<p><a class="a-custom-class" href="/static/path/to/file_name.html">File Name</a></p>
<p><a class="a-custom-class" href="/static/path/to/file-name.html">File Name</a></p>
<p><a class="a-custom-class" href="/static/path/to/file-name.html?a=b&b=c">File Name</a></p>
<p><a class="a-custom-class" href="/static/path/to/file-name.html">File Name</a></p>
<p><a class="a-custom-class" href="/static/path/to/file-name.html?a=b&b=c">File Name</a></p>
<p><a class="a-custom-class" href="https://www.example.com/">www.example.com</a></p>
<p><a class="a-custom-class" href="https://www.example.com/?a=b&b=c">www.example.com</a></p>
<p><a class="a-custom-class" href="https://www.example.com/example-tutorial">Example Tutorial</a></p>
<p><a class="a-custom-class" href="https://www.example.com/example-tutorial">Example Tutorial</a></p>
With meta (markdown.extensions.meta
)
With the following meta added to the markdown:
wiki_base_url: /static/
wiki_end_url:
wiki_url_whitespace: _
wiki_label_case: capitalize
wiki_html_class: wikilink
the output will be:
<p><a class="wikilink" href="/static/wikilink">Wikilink</a> <code>[[wikilink]]</code></p>
<p><a class="wikilink" href="/static/path/to/file_name">File name</a></p>
<p><a class="wikilink" href="/static/path/to/file_name">File name</a></p>
<p><a class="wikilink" href="/static/path/to/file-name">File name</a></p>
<p><a class="wikilink" href="/static/path/to/file_name/?a=b&b=c">File name</a></p>
<p><a class="wikilink" href="/static/path/to/file_name.html">File name</a></p>
<p><a class="wikilink" href="/static/path/to/file_name.html?a=b&b=c">File name</a></p>
<p><a class="wikilink" href="https://www.example.com/">www.example.com</a></p>
<p><a class="wikilink" href="https://www.example.com/?a=b&b=c">www.example.com</a></p>
<p><a class="wikilink" href="https://www.example.com/example-tutorial">Example tutorial</a></p>
<p><a class="wikilink" href="https://www.example.com/example-tutorial">Example Tutorial</a></p>
The build_url callable
The default build_url
function is defined as:
def build_url(urlo, base, end, url_whitespace):
""" Build and return a valid url.
Parameters
----------
urlo A ParseResult object returned by urlparse
base base_url from config
end end_url from config
url_whitespace url_whitespace from config
Returns
-------
URL string
"""
if not urlo.netloc:
if not end:
clean_target = re.sub(r'\s+', url_whitespace, urlo.path)
else:
clean_target = re.sub(r'\s+', url_whitespace, urlo.path.rstrip('/'))
if clean_target.endswith(end):
end = ''
if base.endswith('/'):
path = "%s%s%s" % (base, clean_target.lstrip('/'), end)
elif base and not clean_target.startswith('/'):
path = "%s/%s%s" % (base, clean_target, end)
else:
path = "%s%s%s" % (base, clean_target, end)
urlo = urlo._replace(path=path)
return urlunparse(urlo)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for mdx_wikilink_plus-1.0.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 33b7280bb601402f0e81d2431c24c8c1738e95a9a346dfda03f1f081b42596cc |
|
MD5 | eaea6c64f0df9da02ef57568ad21d100 |
|
BLAKE2b-256 | 21ce5a145e6dc75db61d7e6a661289ceb89437ca0892b5e3148d7a81273900fd |