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