From ec46692cf5c4d5e22950bc8e7d14cb0ec327fb87 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 7 Mar 2012 09:35:40 -0500 Subject: 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. --- docs/extensions/wikilinks.txt | 150 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/extensions/wikilinks.txt (limited to 'docs/extensions/wikilinks.txt') diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt new file mode 100644 index 0000000..b5e2b04 --- /dev/null +++ b/docs/extensions/wikilinks.txt @@ -0,0 +1,150 @@ +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: + + Bracketed + +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 + + Wiki Link + +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]]`. + + WikiLink + +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`. + + WikiLink + +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`): + +

A WikiLink in the first paragraph.

+ -- cgit v1.2.3