[](https://travis-ci.org/neurobin/mdx_wikilink_plus)
Converts wikilinks (`[[wikilink]]`) to relative links, including support for [GitHub image variant](https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/editing-wiki-content#linking-to-images-in-a-repository). 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 must not use this extension with markdown.extensions.wikilinks. This extension is designed to provide the functionalities of markdown.extensions.wikilinks with some extra features. Choose either one.**
# Install
```bash
pip install mdx_wikilink_plus
```
# Wikilink syntax
The geneal formats are:
1. Without explicit label: `[[wikilink]]`
2. With explicit label: `[[ link | label ]]`
- only supported for links not images
3. Image: `[[image.ext]]`
- supports: .png, .jpg, .jpeg or .gif
4. Image alt text: `[[image.ext|alt=alternate text]]`
# Usage
`import markdown` then:
```python
text = "[[wikilink]]"
md = markdown.Markdown(extensions=['mdx_wikilink_plus'])
html = md.convert(text)
```
# Quick examples
`[[/path/to/file-name]]` will become:
```html
<p><a class="wikilink" href="/path/to/file-name">File Name</a></p>
```
`[[/path/to/file name.jpg| alt= alt text]]` will become:
```html
<p><img alt="alt text" class="wikilink-image" src="/path/to/file-name.jpg" /></p>
```
`[[https://www.example.com/example-tutorial]]` will become:
```html
<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:
```html
<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.
url_case | `'none'` | Choose case in the file_path. Available options: lowercase, uppercase.
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.
image_class | `'wikilink-image'` | 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](#the-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](https://python-markdown.github.io/extensions/meta_data/)). Meta-data consists of a series of keywords and values which must be defined at the beginning of a markdown document.
The following example uses recognised metadata parameters:
```md
wiki_base_url: /static/
wiki_end_url:
wiki_url_whitespace: _
wiki_url_case: lowercase
wiki_label_case: capitalize
wiki_html_class: wiki-link
wiki_image_class: wiki-image
This is the first paragraph of the document.
```
### An example with configuration:
```python
md_configs = {
'mdx_wikilink_plus': {
'base_url': '/static',
'end_url': '.html',
'url_case': 'lowercase',
'html_class': 'a-custom-class',
#'build_url': build_url, # A callable
# all of the above config params are optional
},
}
text = """
[[Page Name]]
[[/path/to/file-name.png|alt=demo image]]
[[/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:
```html
<p><a class="a-custom-class" href="/static/page-name.html">Page Name</a></p>
<p><img alt="demo image" class="wikilink-image" src="/static/path/to/file-name.png" /></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
More examples are given in the [test markdown code](https://github.com/neurobin/mdx_wikilink_plus/blob/master/mdx_wikilink_plus/test.py) which demonstrates defaults with no config, a config, meta and build_url.
## With meta (`markdown.extensions.meta`)
If meta is used it must be added to the start of the markdown. eg:
```md
wiki_base_url: /local
wiki_url_whitespace: _
wiki_url_case: lowercase
wiki_label_case: capitalize
wiki_html_class: wiki-lnk
wiki_image_class: wiki-img
```
# The build_url callable
You can view the default [build_url](https://github.com/neurobin/mdx_wikilink_plus/blob/master/mdx_wikilink_plus/mdx_wikilink_plus.py#L36) function which can be customized in python.
Raw data
{
"_id": null,
"home_page": "https://github.com/neurobin/mdx_wikilink_plus",
"name": "mdx-wikilink-plus",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "markdown wikilinks wikilink wikilink_plus",
"author": "Md. Jahidul Hamid",
"author_email": "jahidulhamid@yahoo.com",
"download_url": "https://files.pythonhosted.org/packages/93/ec/b0967db0ec70bfe249359804319a9854491e20bfc06ed4a5e2470095e76a/mdx_wikilink_plus-1.4.1.tar.gz",
"platform": null,
"description": "[](https://travis-ci.org/neurobin/mdx_wikilink_plus)\n\nConverts wikilinks (`[[wikilink]]`) to relative links, including support for [GitHub image variant](https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/editing-wiki-content#linking-to-images-in-a-repository). 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).\n\n**You must not use this extension with markdown.extensions.wikilinks. This extension is designed to provide the functionalities of markdown.extensions.wikilinks with some extra features. Choose either one.**\n\n# Install\n\n```bash\npip install mdx_wikilink_plus\n```\n\n# Wikilink syntax\n\nThe geneal formats are:\n\n1. Without explicit label: `[[wikilink]]`\n2. With explicit label: `[[ link | label ]]`\n - only supported for links not images\n3. Image: `[[image.ext]]`\n - supports: .png, .jpg, .jpeg or .gif\n4. Image alt text: `[[image.ext|alt=alternate text]]`\n\n# Usage\n\n`import markdown` then:\n\n```python\ntext = \"[[wikilink]]\"\nmd = markdown.Markdown(extensions=['mdx_wikilink_plus'])\nhtml = md.convert(text)\n```\n\n# Quick examples\n\n`[[/path/to/file-name]]` will become:\n\n```html\n<p><a class=\"wikilink\" href=\"/path/to/file-name\">File Name</a></p>\n```\n\n`[[/path/to/file name.jpg| alt= alt text]]` will become:\n\n```html\n<p><img alt=\"alt text\" class=\"wikilink-image\" src=\"/path/to/file-name.jpg\" /></p>\n```\n\n`[[https://www.example.com/example-tutorial]]` will become:\n\n```html\n<p><a class=\"wikilink\" href=\"https://www.example.com/example-tutorial\">Example Tutorial</a></p>\n```\n\nand `[[https://www.example.com/?a=b&b=c]]` will become:\n\n```html\n<p><a class=\"wikilink\" href=\"https://www.example.com/?a=b&b=c\">www.example.com</a></p>\n```\n\n\n## Configuration\n\nThe configuration options are:\n\nConfig param | Default | Details\n------------ | ------- | -------\nbase_url | `''` | Prepended to the file_path part of the URL. A `/` at the end of the base_url will be handled intelligently.\nend_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`.\nurl_whitespace | `'-'` | Replace all whitespace in the file_path path with this character (string) when building the URL.\nurl_case | `'none'` | Choose case in the file_path. Available options: lowercase, uppercase.\nlabel_case | `'titlecase'` | Choose case of the label. Available options: titlecase, capitalize, none. Capitalize will capitalize the first character only.\nhtml_class | `'wikilink'` | Set custom HTML classes on the anchor tag. It does not add classes rather it resets any previously set value.\nimage_class | `'wikilink-image'` | Set custom HTML classes on the anchor tag. It does not add classes rather it resets any previously set value.\nbuild_url | `mdx_wikilink_plus.build_url` | A callable that returns the URL string. [Default build_url callable](#the-build_url-callable)\n\n**None of the configs apply on absolute URLs except html_class and build_url. (Yes, label_case won't work either)**\n\n### Configuration through meta data\n\nConfiguration can also be passed through metadata ([markdown.extensions.meta](https://python-markdown.github.io/extensions/meta_data/)). Meta-data consists of a series of keywords and values which must be defined at the beginning of a markdown document.\n\nThe following example uses recognised metadata parameters:\n\n```md\nwiki_base_url: /static/\nwiki_end_url: \nwiki_url_whitespace: _\nwiki_url_case: lowercase\nwiki_label_case: capitalize\nwiki_html_class: wiki-link\nwiki_image_class: wiki-image\n\nThis is the first paragraph of the document.\n```\n\n\n### An example with configuration:\n\n\n```python\nmd_configs = {\n 'mdx_wikilink_plus': {\n 'base_url': '/static',\n 'end_url': '.html',\n 'url_case': 'lowercase',\n 'html_class': 'a-custom-class',\n #'build_url': build_url, # A callable\n # all of the above config params are optional\n },\n }\n\n\ntext = \"\"\"\n[[Page Name]]\n\n[[/path/to/file-name.png|alt=demo image]]\n\n[[/path/to/file name/?a=b&b=c]]\n\"\"\"\n\n\nmd = markdown.Markdown(extensions=['mdx_wikilink_plus'], extension_configs=md_configs)\nprint(md.convert(text))\n```\n\nThe output will be:\n\n```html\n<p><a class=\"a-custom-class\" href=\"/static/page-name.html\">Page Name</a></p>\n<p><img alt=\"demo image\" class=\"wikilink-image\" src=\"/static/path/to/file-name.png\" /></p>\n<p><a class=\"a-custom-class\" href=\"/static/path/to/file-name.html?a=b&b=c\">File Name</a></p>\n```\n\n!!! info\n `end_url` is added at the end of the file-path part in the URL.\n\n-----\n\n# More examples\n\nMore examples are given in the [test markdown code](https://github.com/neurobin/mdx_wikilink_plus/blob/master/mdx_wikilink_plus/test.py) which demonstrates defaults with no config, a config, meta and build_url.\n\n## With meta (`markdown.extensions.meta`)\n\nIf meta is used it must be added to the start of the markdown. eg:\n\n```md\nwiki_base_url: /local\nwiki_url_whitespace: _\nwiki_url_case: lowercase\nwiki_label_case: capitalize\nwiki_html_class: wiki-lnk\nwiki_image_class: wiki-img\n```\n\n# The build_url callable\n\nYou can view the default [build_url](https://github.com/neurobin/mdx_wikilink_plus/blob/master/mdx_wikilink_plus/mdx_wikilink_plus.py#L36) function which can be customized in python.\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A wikilink extension for Python Markdown",
"version": "1.4.1",
"split_keywords": [
"markdown",
"wikilinks",
"wikilink",
"wikilink_plus"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "2d51ed5881555674539478bc59a661a6",
"sha256": "bf1a06cdf4e60484c64afb4d2069a07ca70263ebf56387a1da397d1ca182ab70"
},
"downloads": -1,
"filename": "mdx_wikilink_plus-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d51ed5881555674539478bc59a661a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8920,
"upload_time": "2022-07-26T06:02:33",
"upload_time_iso_8601": "2022-07-26T06:02:33.801785Z",
"url": "https://files.pythonhosted.org/packages/bb/9c/47120c866c56c6f0357428e07c057b2ad277a89f5e698d5110fd37688333/mdx_wikilink_plus-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "1574709a84cb5aedb8249b0c1e9c6260",
"sha256": "b82446c00a49a57a5ccab48e6053168397f6ed818d2183a8a0f7472aa0e8e3ca"
},
"downloads": -1,
"filename": "mdx_wikilink_plus-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "1574709a84cb5aedb8249b0c1e9c6260",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9896,
"upload_time": "2022-07-26T06:02:36",
"upload_time_iso_8601": "2022-07-26T06:02:36.608966Z",
"url": "https://files.pythonhosted.org/packages/93/ec/b0967db0ec70bfe249359804319a9854491e20bfc06ed4a5e2470095e76a/mdx_wikilink_plus-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-07-26 06:02:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "neurobin",
"github_project": "mdx_wikilink_plus",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "mdx-wikilink-plus"
}
JSON
