diff options
Diffstat (limited to 'docs/extensions')
| -rw-r--r-- | docs/extensions/Abbreviations.txt | 53 | ||||
| -rw-r--r-- | docs/extensions/CodeHilite.txt | 113 | ||||
| -rw-r--r-- | docs/extensions/Definition_Lists.txt | 55 | ||||
| -rw-r--r-- | docs/extensions/Fenced_Code_Blocks.txt | 63 | ||||
| -rw-r--r-- | docs/extensions/HTML_Tidy.txt | 27 | ||||
| -rw-r--r-- | docs/extensions/HeaderId.txt | 104 | ||||
| -rw-r--r-- | docs/extensions/ImageLinks.txt | 27 | ||||
| -rw-r--r-- | docs/extensions/Meta-Data.txt | 88 | ||||
| -rw-r--r-- | docs/extensions/RSS.txt | 35 | ||||
| -rw-r--r-- | docs/extensions/Tables.txt | 53 | ||||
| -rw-r--r-- | docs/extensions/Tables_of_Contents.txt | 50 | ||||
| -rw-r--r-- | docs/extensions/WikiLinks.txt | 144 | ||||
| -rw-r--r-- | docs/extensions/extra.txt | 43 | ||||
| -rw-r--r-- | docs/extensions/footnotes.txt | 62 | ||||
| -rw-r--r-- | docs/extensions/index.txt | 44 |
15 files changed, 961 insertions, 0 deletions
diff --git a/docs/extensions/Abbreviations.txt b/docs/extensions/Abbreviations.txt new file mode 100644 index 0000000..fa54d3c --- /dev/null +++ b/docs/extensions/Abbreviations.txt @@ -0,0 +1,53 @@ +Abbreviations +------------- + +Summary +------- + +The Markdown Abbreviation Extension adds the ability to define abbreviations. +Specifically, any defined abbreviation is wrapped in an `<abbr>` tag. + +The Abbreviation extension is included in the standard Markdown library. + +Syntax +------ + +Abbreviations are defined using the syntax established in +[PHP Markdown Extra][php]. + +[php]: http://www.michelf.com/projects/php-markdown/extra/#abbr + +Thus, the following text (taken from the above referenced PHP documentation): + + The HTML specification + is maintained by the W3C. + + *[HTML]: Hyper Text Markup Language + *[W3C]: World Wide Web Consortium + +will be rendered like so: + + <p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification + is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p> + +Usage +----- + +From the Python interpreter: + + >>> import markdown + >>> text = """ + ... Some text with an ABBR. + ... + ... *[ABBR]: Abbreviation + ... """ + >>> html = markdown.markdown(text, ['abbr']) + +To use with other extensions, just add them to the list, like this: + + >>> html = markdown.markdown(text, ['abbr', 'footnotes']) + +Abbreviations can also be called from the command line using Markdown's `-x` +parameter, like so: + + markdown.py -x abbr source.txt > output.html diff --git a/docs/extensions/CodeHilite.txt b/docs/extensions/CodeHilite.txt new file mode 100644 index 0000000..482ad60 --- /dev/null +++ b/docs/extensions/CodeHilite.txt @@ -0,0 +1,113 @@ +CodeHilite +========== + +Summary +------- + +The CodeHilite Extension adds code/syntax highlighting to standard +Python-Markdown code blocks using [Pygments][]. + +[Python-Markdown]: http://www.freewisdom.org/projects/python-markdown/ +[Pygments]: http://pygments.org/ + +This extension is included in the Markdown library. + +Setup +----- + +You will also need to [download][dl] and install the Pygments package on your +`PYTHONPATH`. You will need to determine the appropriate CSS classes and create +appropriate rules for them, which are either defined in or linked from the +header of your HTML templates. See the excellent [documentation][] for more +details. If no language is defined, Pygments will attempt to guess the +language. When that fails, the code block will display as un-highlighted code. + +[dl]: http://pygments.org/download/ +[documentation]: http://pygments.org/docs + +**Note:** The css and/or javascript is not included as part of this extension +but shall always be provided by the end user. + +Syntax +------ + +The CodeHilite Extension follows the same [syntax][] as regular Markdown code +blocks, with one exception. The hiliter needs to know what language to use for +the code block. There are three ways to tell the hiliter what language the code +block contains and each one has a different result. + +[syntax]: http://daringfireball.net/projects/markdown/syntax#precode + +###SheBang (with path) + +If the first line of the codeblock contains a shebang, the language is derived +from that and line numbers are used. + + #!/usr/bin/python + # Code goes here ... + +Will result in: + + #!/usr/bin/python + # Code goes here ... + + +###SheBang (no path) + +If the first line contains a shebang, but the shebang line does not contain a +path (a single `/` or even a space), then that line is removed from the code +block before processing. Line numbers are used. + + #!python + # Code goes here ... + +Will result in: + + # Code goes here ... + +####Colons + +If the first line begins with three or more colons, the text following the +colons identifies the language. The first line is removed from the code block +before processing and line numbers are not used. + + :::python + # Code goes here ... + +Will result in: + + # Code goes here ... + +###When No Language is Defined + +CodeHilite is completely backward compatible so that if a code block is +encountered that does not define a language, the block is simple wrapped in +`<pre>` tags and output. Note: one exception would be that the Pygments +highlighting engine will try to guess the language. Upon failure, the same +behavior will happen as described here. + + # Code goes here ... + +Will result in: + + # Code goes here ... + +Lets see the source for that: + + <div class="codehilite" ><pre><code># Code goes here ... + </code></pre></div> + +Usage +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['codehilite']) + +If you want every code block to have line numbers, even when using colons +(`:::`) for language identification, the setting `force_linenos` is available +to do so. + + >>> html = markdown.markdown(text, + ... ['codehilite(force_linenos=True)'] + ... ) diff --git a/docs/extensions/Definition_Lists.txt b/docs/extensions/Definition_Lists.txt new file mode 100644 index 0000000..983070d --- /dev/null +++ b/docs/extensions/Definition_Lists.txt @@ -0,0 +1,55 @@ +Definition Lists +---------------- + +Summary +------- + +The Definition List Extension adds the ability to create definition list in +Markdown documents. + +This extension is included in the standard Markdown library. + +Syntax +------ + +Definition lists are defined using the syntax established in +[PHP Markdown Extra][php]. + +[php]: http://www.michelf.com/projects/php-markdown/extra/#def-list + +Thus, the following text (taken from the above referenced PHP documentation): + + Apple + : Pomaceous fruit of plants of the genus Malus in + the family Rosaceae. + + Orange + : The fruit of an evergreen tree of the genus Citrus. + +will be rendered like so: + + <dl> + <dt>Apple</dt> + <dd>Pomaceous fruit of plants of the genus Malus in + the family Rosaceae.</dd> + + <dt>Orange</dt> + <dd>The fruit of an evergreen tree of the genus Citrus.</dd> + </dl> + + +Usage +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['def_list']) + +To use with other extensions, just add them to the list, like this: + + >>> html = markdown.markdown(text, ['def_list', 'footnotes']) + +The extension can also be called from the command line using Markdown's `-x` +parameter: + + markdown.py -x def_list source.txt > output.html diff --git a/docs/extensions/Fenced_Code_Blocks.txt b/docs/extensions/Fenced_Code_Blocks.txt new file mode 100644 index 0000000..6b1ba76 --- /dev/null +++ b/docs/extensions/Fenced_Code_Blocks.txt @@ -0,0 +1,63 @@ +Fenced Code Blocks +================== + +Summary +------- + +This extension adds a secondary way to define code blocks which overcomes a few +limitations of the indented code blocks. + +This extension is included in the standard Markdown library. + +Syntax +------ + +Fenced Code Blocks are defined using the syntax established in +[PHP Markdown Extra][php]. + +[php]: http://www.michelf.com/projects/php-markdown/extra/#fenced-code-blocks + +Thus, the following text (taken from the above referenced PHP documentation): + + This is a paragraph introducing: + + ~~~~~~~~~~~~~~~~~~~~ + a one-line code block + ~~~~~~~~~~~~~~~~~~~~ + +Fenced code blocks can have a blank line as the first and/or last line of a +code block and they can also come immediately after a list item without becoming +part of the list. + +In addition to PHP Extra's syntax, you can define the language of the code +block for use by syntax highlighters etc. The language will be assigned as a +class attribute of the ``<code>`` element in the output. Therefore, you should +define the language as you would a css class - ``.language``. For consistency +with other markdown syntax, the language can *optionally* be wrapped in curly +brackets: + + ~~~~{.python} + # python code + ~~~~ + + ~~~~.html + <p>HTML Document</p> + ~~~~ + +The above will output: + + <pre><code class="python"># python code + </code></pre> + + <pre><code class="html"><p>HTML Document</p> + </code></pre> + +Usage +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['fenced_code']) + + + diff --git a/docs/extensions/HTML_Tidy.txt b/docs/extensions/HTML_Tidy.txt new file mode 100644 index 0000000..52f991f --- /dev/null +++ b/docs/extensions/HTML_Tidy.txt @@ -0,0 +1,27 @@ +HTML Tidy +========= + +Runs [HTML Tidy][] on the output of Python-Markdown using the [uTidylib][] +Python wrapper. Both libtidy and uTidylib must be installed on your system. + +This extension is available in the standard Markdown library since version 2.0. + +[HTML Tidy]: http://tidy.sourceforge.net/ +[uTidylib]: http://utidylib.berlios.de/ + +Note than any Tidy [options][] can be passed in as extension configs. So, +for example, to output HTML rather than XHTML, set ``output_xhtml=0``. To +indent the output, set ``indent=auto`` and to have Tidy wrap the output in +``<html>`` and ``<body>`` tags, set ``show_body_only=0``. See Tidy's +[options][] for a full list of the available options. The defaults are set to +most closely match Markdowns defaults with the exception that you get much +better pretty-printing. + +[options]: http://tidy.sourceforge.net/docs/quickref.html + +Note that options set in this extension will override most any other settings +passed on to Markdown (such as "output_format"). Unlike Markdown, this extension +will also treat raw HTML no different than that output by Markdown. In other +words, it may munge a document authors carefully crafted HTML. Of course, it +may also transform poorly formed raw HTML into nice, valid HTML. Take these +things into consideration when electing to use this extension. diff --git a/docs/extensions/HeaderId.txt b/docs/extensions/HeaderId.txt new file mode 100644 index 0000000..efd1eb8 --- /dev/null +++ b/docs/extensions/HeaderId.txt @@ -0,0 +1,104 @@ +HeaderId +======== + +Summary +------- + +An extension to Python-Markdown that adds an 'id' attribute to HTML header +elements (h1-h6) in markdown's output. + +This extension is included in the standard Markdown library. + +Syntax +------ + +The basic syntax follows [PHP Markdown Extra][]'s implementation: + +[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#header-id + + Header 1 {#header1} + ======== + + ## Header 2 ## {#header2} + +will result in the following HTML: + + <h1 id="header1">Header 1</h1> + + <h2 id="header2">Header 2</h2> + +However, there is much more that this extension does. + +By default, all headers will automatically have unique "id" attributes +generated based upon the text of the header (See below to turn this off). +Note this example in which all three headers would have the same "id": + + #Header + #Another Header {#header} + #Header + +Results in: + + <h1 id="header">Header</h1> + <h1 id="header_1">Another Header</h1> + <h1 id="header_2">Third Header</h1> + +Configuring the Output +---------------------- + +The HeaderId extension has two configuration settings: + +* **level**: Base level for headers. + + Default: `1` + +* **forceid**: Force all headers to have an id. + + Default: `True` + +The `level` setting allows you to automatically adjust the header levels to fit +within the hierarchy of your html templates. For example, the markdown text for +this page should not contain any headers higher than level 3 (`<h3>`). +Therefore, do the following: + + >>> text = ''' + ... #Some Header + ... ## Next Level''' + >>> html = markdown.markdown(text, ['headerid(level=3)']) + >>> print html + <h3 id="some_header">Some Header</h3> + <h4 id="next_level">Next Level</h4>' + +The `forceid` setting turns on or off the automatically generated ids for +headers that do not have one explicitly defined. + + >>> text = ''' + ... # Some Header + ... # Header with ID # { #foo }''' + >>> html = markdown.markdown(text, ['headerid(forceid=False)']) + >>> print html + <h1>Some Header</h1> + <h1 id="foo">Header with ID</h1> + +Using with Meta-Data +-------------------- + +The HeaderId Extension also supports the [[Meta-Data]] Extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are: + +* `header_level` +* `header_forceid` + +When used, the meta-data will override the settings provided through the +`extension_configs` interface. + +This document: + + header_level: 2 + header_forceid: Off + + # A Header + + +Will result in the following output: + + <h2>A Header</h2> diff --git a/docs/extensions/ImageLinks.txt b/docs/extensions/ImageLinks.txt new file mode 100644 index 0000000..db4f99f --- /dev/null +++ b/docs/extensions/ImageLinks.txt @@ -0,0 +1,27 @@ +ImageLinks +========== + +Summary +------- + +ImageLinks is a Python-Markdown extension that provides a mechanism for +defining mini-photo galleries within a markdown document. + +This extension is part of the Markdown library since 2.0. + +Syntax +------ + +Turns paragraphs like + + <~~~~~~~~~~~~~~~~~~~~~~~~ + dir/subdir + dir/subdir + dir/subdir + ~~~~~~~~~~~~~~ + dir/subdir + dir/subdir + dir/subdir + ~~~~~~~~~~~~~~~~~~~> + +Into mini-photo galleries. diff --git a/docs/extensions/Meta-Data.txt b/docs/extensions/Meta-Data.txt new file mode 100644 index 0000000..982ea67 --- /dev/null +++ b/docs/extensions/Meta-Data.txt @@ -0,0 +1,88 @@ +Meta-Data +========= + +Summary +------- + +An extension to Python-Markdown that adds a syntax for defining meta-data about +a document. The Meta-Data extension is inspired by and follows the syntax of +[MultiMarkdown][]. Currently, this extension does not use the meta-data in any +way, but simply provides it as a `Meta` attribute of a markdown instance for +use by other extensions or directly by your python code. + +[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata + +This extension has been a part of the Markdown library since 2.0. + +Syntax +------ + +Meta-data consists of a series of keywords and values defined at the beginning +of a markdown document like this: + + Title: My Document + Summary: A brief description of my document. + Authors: Waylan Limberg + John Doe + Date: October 2, 2007 + blank-value: + base_url: http://example.com + + This is the first paragraph of the document. + +The keywords are case-insensitive and may consist of letters, numbers, +underscores and dashes and must end with a colon. The values consist of +anything following the colon on the line and may even be blank. If a line is +indented 4 or more spaces, that line is assumed to be an additional line of the +value for the previous keyword. A keyword may have as many lines as desired. +The first blank line ends all meta-data for the document. Therefore, the first +line of a document must not be blank. All meta-data is stripped from the +document prior to any further processing by markdown. + +Accessing the Meta-Data +----------------------- + +The meta-data is made available as a python Dict in the `Meta` attribute of an +instance of the Markdown class. For example, using the above document: + + >>> md = markdown.Markdown(extensions = ['meta']) + >>> html = md.convert(text) + >>> # Meta-data has been stripped from output + >>> print html + <p>This is the first paragraph of the document.</p> + + >>> # View meta-data + >>> print md.Meta + { + 'title' : ['My Document'], + 'summary' : ['A brief description of my document.'], + 'authors' : ['Waylan Limberg', 'John Doe'], + 'date' : ['October 2, 2007'], + 'blank-value' : [''], + 'base_url' : ['http://example.com'] + } + +Note that the keys are all lowercase and the values consist of a list of +strings where each item is one line for that key. This way, one could preserve +line breaks if desired. Or the items could be joined where appropriate. No +assumptions are made regarding the data. It is simply passed as found to the +`Meta` attribute. + +Perhaps the meta-data could be passed into a template system, or used by +various markdown extensions. The possibilities are left to the imagination of +the developer. + +Compatible Extensions +--------------------- + +The following are extensions currently known to work with the Meta-Data +Extension and the keywords they are known to support: + +* [[HeaderId]] + * `header_level` + * `header_forceid` +* [[WikiLinks]] + * `wiki_base_url` + * `wiki_end_url` + * `wiki_html_class` + diff --git a/docs/extensions/RSS.txt b/docs/extensions/RSS.txt new file mode 100644 index 0000000..f2ecf0c --- /dev/null +++ b/docs/extensions/RSS.txt @@ -0,0 +1,35 @@ +RSS +=== + +Summary +------- + +An extension to Python-Markdown that outputs a markdown document as RSS. This +extension has been included with Python-Markdown since 1.7 and should be +available to anyone who has a typical install of Python-Markdown. + +Usage +----- + +From the Python interpreter: + + >>> import markdown + >>> text = "Some markdown document." + >>> rss = markdown.markdown(text, ['rss']) + +Configuring the Output +---------------------- + +An RSS document includes some data about the document (URI, author, title) that +will likely need to be configured for your needs. Therefore, three configuration +options are available: + +* **URL** : The Main URL for the document. +* **CREATOR** : The Feed creator's name. +* **TITLE** : The title for the feed. + +An example: + + >>> rss = markdown.markdown(text, extensions = \ + ... ['rss(URL=http://example.com,CREATOR=JOHN DOE,TITLE=My Document)'] + ... ) diff --git a/docs/extensions/Tables.txt b/docs/extensions/Tables.txt new file mode 100644 index 0000000..63d6849 --- /dev/null +++ b/docs/extensions/Tables.txt @@ -0,0 +1,53 @@ +Tables +---------------- + +Summary +------- + +The Table Extension adds the ability to create tables in Markdown documents. + +This extension is included in the standard Markdown library. + +Syntax +------ + +Tables are defined using the syntax established in [PHP Markdown Extra][php]. + +[php]: http://www.michelf.com/projects/php-markdown/extra/#table + +Thus, the following text (taken from the above referenced PHP documentation): + +First Header | Second Header +------------- | ------------- +Content Cell | Content Cell +Content Cell | Content Cell + +will be rendered as: + +<table> +<thead> +<tr> +<th>First Header</th> +<th>Second Header</th> +</tr> +</thead> +<tbody> +<tr> +<td>Content Cell</td> +<td>Content Cell</td> + +</tr> +<tr> +<td>Content Cell</td> +<td>Content Cell</td> +</tr> +</tbody> +</table> + +Usage +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['tables']) + diff --git a/docs/extensions/Tables_of_Contents.txt b/docs/extensions/Tables_of_Contents.txt new file mode 100644 index 0000000..032c25c --- /dev/null +++ b/docs/extensions/Tables_of_Contents.txt @@ -0,0 +1,50 @@ +Table of Contents +================= + +Summary +------- + +Adds a Table of Contents to a Markdown document. + +This extension is included with the Markdown library since version 2.0. + +Syntax +------ + +Place a marker in the document where you would like the table of contents to +appear. Then, a nested list of all the headers in the document will replace the +marker. The marker defaults to ``[TOC]`` so the following document: + + [TOC] + + # Header 1 + + ## Header 2 + +would generate the following output: + + <div class="toc"> + <ul> + <li><a href="#header-1">Header 1</a></li> + <ul> + <li><a href="#header-2">Header 2</a></li> + </ul> + </ul> + </div> + <h1 id="header-1">Header 1</h1> + <h1 id="header-2">Header 2</h1> + +Configuration Options +--------------------- + +The following options are provided to configure the output: + +* **marker**: Text to find and replace with the Table of Contents. Defaults + to ``[TOC]``. +* **slugify**: Callable to generate anchors based on header text. Defaults to a + built in ``slugify`` method. The callable must accept one argument which + contains the text content of the header and return a string which will be + used as the anchor text. +* **title**: Title to insert in TOC ``<div>``. Defaults to ``None``. +* **anchorlink**: Set to ``True`` to have the headers link to themselves. + Default is ``False``. diff --git a/docs/extensions/WikiLinks.txt b/docs/extensions/WikiLinks.txt new file mode 100644 index 0000000..8bbead5 --- /dev/null +++ b/docs/extensions/WikiLinks.txt @@ -0,0 +1,144 @@ +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]] 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> + diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt new file mode 100644 index 0000000..817d58f --- /dev/null +++ b/docs/extensions/extra.txt @@ -0,0 +1,43 @@ +Python-Markdown Extra +===================== + +Summary +------- + +A compilation of various Python-Markdown extensions that (mostly) imitates +[PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/). + +The supported extensions include: + +* [[Abbreviations]] +* [[Definition_Lists]] +* [[Fenced_Code_Blocks]] +* [[Footnotes]] +* [[HeaderId]] +* [[Tables]] + +See each individual extension for syntax documentation. Extra and all it's +supported extensions are included in the standard Markdown library. + +Usage +----- + +From the Python interpreter: + + >>> import markdown + >>> html = markdown.markdown(text, ['extra']) + +In the unlikely event that one or more of the supported extensions are not +available for import, Markdown will simply continue without that +extension. If you would like to be notified of such failures, +you may set Python-Markdown's logger level to "WARN". + +There may be additional extensions that are distributed with +Python-Markdown that are not included here in Extra. Those extensions +are not part of PHP Markdown Extra, and therefore, not part of +Python-Markdown Extra. If you really would like Extra to include +additional extensions, we suggest creating your own clone of Extra +under a different name (see [[Writing Extensions]]). You could also +edit the `extensions` global variable defined in the source, but be +aware that such changes may be lost when you upgrade to any future +version of Python-Markdown. diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt new file mode 100644 index 0000000..7188f44 --- /dev/null +++ b/docs/extensions/footnotes.txt @@ -0,0 +1,62 @@ +Footnotes +========= + +Summary +------- + +An extension to Python-Markdown that adds footnote syntax. This extension has +been included with Python-Markdown since 1.7 and should be available to anyone +who has a typical install of Python-Markdown. + +Syntax +------ + +Python-Markdown's Footnote syntax follows the generally accepted syntax of the +Markdown community at large and almost exactly matches [PHP Markdown Extra][]'s +implementation of footnotes. The only differences involve a few subtleties in +the output. + +[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#footnotes + +Example: + + Footnotes[^1] have a label[^label] and a definition[^!DEF]. + + [^1]: This is a footnote + [^label]: A footnote on "label" + [^!DEF]: The definition of a footnote. + +A footnote definition may contain multiple lines, paragraphs, code blocks, +blockquotes and most any other markdown syntax. The additional line simply +must be indented at least an additional four spaces. + + [^1]: The first paragraph of the definition. + + Paragraph two of the definition. + + > A blockquote with + > multiple lines. + + a code block + + A final paragraph. + +By default, the footnote definitions are placed at the end of the resulting +HTML document. However, you may want the footnotes in another location within +the document. Simply place the following text at that location within your +markdown document (See how to configure this text below): + + ///Footnotes Go Here/// + +Usage +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['footnotes']) + +To configure the place marker for footnote definitions (just be sure not to +use any existing markdown syntax): + + >>> html = markdown.markdown(text, ['footnotes(PLACE_MARKER=+++my marker+++)']) + diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt new file mode 100644 index 0000000..71d857c --- /dev/null +++ b/docs/extensions/index.txt @@ -0,0 +1,44 @@ +Available Extensions +==================== + +Officially Supported Extensions +------------------------------- + +These extensions are included with (at least) the most recent release and are +officially supported by the Python-Markdown developers. Any documentation is +maintained here and all bug reports should be made to the project. If you +have a typical install of Python-Markdown, these extensions are already +available to you. + +* [[Extra]] + * [[Abbreviations]] + * [[Definition_Lists]] + * [[Fenced_Code_Blocks]] + * [[Footnotes]] + * [[HeaderId]] + * [[Tables]] +* [[CodeHilite]] +* [[HTML_Tidy]] +* [[ImageLinks]] +* [[Meta-Data]] +* [[RSS]] +* [[Table_of_Contents]] +* [[WikiLinks]] + +Unofficially Supported Extensions +--------------------------------- + +These extensions have not yet been included in any official Python-Markdown +release. However, the code is maintained in the projects +[mainline git repository](http://gitorious.org/projects/python-markdown/repos/mainline) +by the Python-Markdown developers and the official documentation is maintained +here. All bug reports should be made to the project. It is anticipated that +these extensions will be included with some future official release, at which +time they will be moved to the above list of official extensions. + +* [[Legacy]] + + + + + |