diff options
author | Waylan Limberg <waylan@gmail.com> | 2012-03-07 09:35:40 -0500 |
---|---|---|
committer | Waylan Limberg <waylan@gmail.com> | 2012-03-07 09:35:40 -0500 |
commit | ec46692cf5c4d5e22950bc8e7d14cb0ec327fb87 (patch) | |
tree | 9c1b9c5025948204e415a21938469bf50bbae754 /docs/extensions/wikilinks.md | |
parent | 9fd4a5f1600c96406ad0fb86b1a8287d525972ac (diff) | |
download | markdown-ec46692cf5c4d5e22950bc8e7d14cb0ec327fb87.tar.gz markdown-ec46692cf5c4d5e22950bc8e7d14cb0ec327fb87.tar.bz2 markdown-ec46692cf5c4d5e22950bc8e7d14cb0ec327fb87.zip |
Rename docs/*.md => docs/*.txt
The documentation uses features of Python-Markdown that are not supported on
GitHub and it's better to get a source view of the docs anyway. For example,
that way comments and bug reports can reference a specific line of a file.
Of course, it makes sense for Github to render the README, so that is left
with the `.md` file extension.
Diffstat (limited to 'docs/extensions/wikilinks.md')
-rw-r--r-- | docs/extensions/wikilinks.md | 150 |
1 files changed, 0 insertions, 150 deletions
diff --git a/docs/extensions/wikilinks.md b/docs/extensions/wikilinks.md deleted file mode 100644 index b5e2b04..0000000 --- a/docs/extensions/wikilinks.md +++ /dev/null @@ -1,150 +0,0 @@ -title: Wikilinks Extension -prev_title: Table of Contents Extension -prev_url: toc.html -next_title: Extension API -next_url: api.html - -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](meta_data.html) 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> - |