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/cli.md | 108 ------ docs/cli.txt | 108 ++++++ docs/extensions/abbreviations.md | 59 ---- docs/extensions/abbreviations.txt | 59 ++++ docs/extensions/api.md | 612 --------------------------------- docs/extensions/api.txt | 612 +++++++++++++++++++++++++++++++++ docs/extensions/attr_list.md | 80 ----- docs/extensions/attr_list.txt | 80 +++++ docs/extensions/code_hilite.md | 126 ------- docs/extensions/code_hilite.txt | 126 +++++++ docs/extensions/definition_lists.md | 61 ---- docs/extensions/definition_lists.txt | 61 ++++ docs/extensions/extra.md | 48 --- docs/extensions/extra.txt | 48 +++ docs/extensions/fenced_code_blocks.md | 69 ---- docs/extensions/fenced_code_blocks.txt | 69 ++++ docs/extensions/footnotes.md | 68 ---- docs/extensions/footnotes.txt | 68 ++++ docs/extensions/header_id.md | 111 ------ docs/extensions/header_id.txt | 111 ++++++ docs/extensions/html_tidy.md | 34 -- docs/extensions/html_tidy.txt | 34 ++ docs/extensions/index.md | 63 ---- docs/extensions/index.txt | 63 ++++ docs/extensions/meta_data.md | 94 ----- docs/extensions/meta_data.txt | 94 +++++ docs/extensions/nl2br.md | 25 -- docs/extensions/nl2br.txt | 25 ++ docs/extensions/rss.md | 41 --- docs/extensions/rss.txt | 41 +++ docs/extensions/sane_lists.md | 81 ----- docs/extensions/sane_lists.txt | 81 +++++ docs/extensions/smart_strong.md | 37 -- docs/extensions/smart_strong.txt | 37 ++ docs/extensions/tables.md | 58 ---- docs/extensions/tables.txt | 58 ++++ docs/extensions/toc.md | 56 --- docs/extensions/toc.txt | 56 +++ docs/extensions/wikilinks.md | 150 -------- docs/extensions/wikilinks.txt | 150 ++++++++ docs/index.md | 66 ---- docs/index.txt | 66 ++++ docs/install.md | 83 ----- docs/install.txt | 83 +++++ docs/reference.md | 244 ------------- docs/reference.txt | 244 +++++++++++++ docs/release-2.0.1.md | 16 - docs/release-2.0.1.txt | 16 + docs/release-2.0.2.md | 9 - docs/release-2.0.2.txt | 9 + docs/release-2.0.md | 67 ---- docs/release-2.0.txt | 67 ++++ docs/release-2.1.0.md | 117 ------- docs/release-2.1.0.txt | 117 +++++++ docs/release-2.1.1.md | 7 - docs/release-2.1.1.txt | 7 + docs/test_suite.md | 133 ------- docs/test_suite.txt | 133 +++++++ 58 files changed, 2723 insertions(+), 2723 deletions(-) delete mode 100644 docs/cli.md create mode 100644 docs/cli.txt delete mode 100644 docs/extensions/abbreviations.md create mode 100644 docs/extensions/abbreviations.txt delete mode 100644 docs/extensions/api.md create mode 100644 docs/extensions/api.txt delete mode 100644 docs/extensions/attr_list.md create mode 100644 docs/extensions/attr_list.txt delete mode 100644 docs/extensions/code_hilite.md create mode 100644 docs/extensions/code_hilite.txt delete mode 100644 docs/extensions/definition_lists.md create mode 100644 docs/extensions/definition_lists.txt delete mode 100644 docs/extensions/extra.md create mode 100644 docs/extensions/extra.txt delete mode 100644 docs/extensions/fenced_code_blocks.md create mode 100644 docs/extensions/fenced_code_blocks.txt delete mode 100644 docs/extensions/footnotes.md create mode 100644 docs/extensions/footnotes.txt delete mode 100644 docs/extensions/header_id.md create mode 100644 docs/extensions/header_id.txt delete mode 100644 docs/extensions/html_tidy.md create mode 100644 docs/extensions/html_tidy.txt delete mode 100644 docs/extensions/index.md create mode 100644 docs/extensions/index.txt delete mode 100644 docs/extensions/meta_data.md create mode 100644 docs/extensions/meta_data.txt delete mode 100644 docs/extensions/nl2br.md create mode 100644 docs/extensions/nl2br.txt delete mode 100644 docs/extensions/rss.md create mode 100644 docs/extensions/rss.txt delete mode 100644 docs/extensions/sane_lists.md create mode 100644 docs/extensions/sane_lists.txt delete mode 100644 docs/extensions/smart_strong.md create mode 100644 docs/extensions/smart_strong.txt delete mode 100644 docs/extensions/tables.md create mode 100644 docs/extensions/tables.txt delete mode 100644 docs/extensions/toc.md create mode 100644 docs/extensions/toc.txt delete mode 100644 docs/extensions/wikilinks.md create mode 100644 docs/extensions/wikilinks.txt delete mode 100644 docs/index.md create mode 100644 docs/index.txt delete mode 100644 docs/install.md create mode 100644 docs/install.txt delete mode 100644 docs/reference.md create mode 100644 docs/reference.txt delete mode 100644 docs/release-2.0.1.md create mode 100644 docs/release-2.0.1.txt delete mode 100644 docs/release-2.0.2.md create mode 100644 docs/release-2.0.2.txt delete mode 100644 docs/release-2.0.md create mode 100644 docs/release-2.0.txt delete mode 100644 docs/release-2.1.0.md create mode 100644 docs/release-2.1.0.txt delete mode 100644 docs/release-2.1.1.md create mode 100644 docs/release-2.1.1.txt delete mode 100644 docs/test_suite.md create mode 100644 docs/test_suite.txt (limited to 'docs') diff --git a/docs/cli.md b/docs/cli.md deleted file mode 100644 index 9babc50..0000000 --- a/docs/cli.md +++ /dev/null @@ -1,108 +0,0 @@ -title: Command Line -prev_title: Library Reference -prev_url: reference.html -next_title: Extensions -next_url: extensions/index.html - - -Using Python-Markdown on the Command Line -========================================= - -While Python-Markdown is primarily a python library, a command line script is -included as well. While there are many other command line implementations -of Markdown, you may not have them installed, or you may prefer to use -Python-Markdown's various extensions. - -Generally, you will want to have the Markdown library fully installed on your -system to run the command line script. See the -[Installation instructions](install.html) for details. - -Assuming the `python` executable is on your system path, just run the following: - - python -m markdown [options] [args] - -That will run the module as a script. Note that on older Python versions (2.5 -and 2.6), you may need to specify the appropriate module: - - python -m markdown.__main__ [options] [args] - -Use the `--help` option for available options: - - python -m markdown --help - -If you are using Python 2.4 or you don't want to have to call the python -executable directly, follow the instructions below: - -Setup ------ - -Upon installation, the ``markdown_py`` script will have been copied to -your Python "Scripts" directory. Different systems require different methods to -ensure that any files in the Python "Scripts" directory are on your system -path. - -* **Windows**: - - Assuming a default install of Python on Windows, your "Scripts" directory - is most likely something like ``C:\\Python26\Scripts``. Verify the location - of your "Scripts" directory and add it to you system path. - - Calling ``markdown_py`` from the command line will call the wrapper batch - file ``markdown_py.bat`` in the "Scripts" directory created during install. - -* __*nix__ (Linux, OSX, BSD, Unix, etc.): - - As each *nix distribution is different and we can't possibly document all - of them here, we'll provide a few helpful pointers: - - * Some systems will automatically install the script on your path. Try it - and see if it works. Just run ``markdown_py`` from the command line. - - * Other systems may maintain a separate "Scripts" directory which you - need to add to your path. Find it (check with your distribution) and - either add it to your path or make a symbolic link to it from your path. - - * If you are sure ``markdown_py`` is on your path, but it still isn't being - found, check the permissions of the file and make sure it is executable. - - As an alternative, you could just ``cd`` into the directory which contains - the source distribution, and run it from there. However, remember that your - markdown text files will not likely be in that directory, so it is much - more convenient to have ``markdown_py`` on your path. - -__Note:__ Python-Markdown uses "markdown_py" as a script name because -the Perl implementation has already taken the more obvious name "markdown". -Additionally, the default Python configuration on some systems would cause a -script named "markdown.py" to fail by importing itself rather than the markdown -library. Therefore, the script has been named "markdown_py" as a compromise. If -you prefer a different name for the script on your system, it is suggested that -you create a symbolic link to `markdown_py` with your preferred name. - -Usage ------ - -To use ``markdown_py`` from the command line, run it as - - $ markdown_py input_file.txt - -or - - $ markdown_py input_file.txt > output_file.html - -For a complete list of options, run - - $ markdown_py --help - -Using Extensions ----------------- - -For an extension to be run from the command line it must be provided in a module -on your python path (see the [Extension API](extensions/api.html) for details). -It can then be invoked by the name of that module: - - $ markdown_py -x footnotes text_with_footnotes.txt > output.html - -If the extension supports config options, you can pass them in as well: - - $ markdown_py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt - diff --git a/docs/cli.txt b/docs/cli.txt new file mode 100644 index 0000000..9babc50 --- /dev/null +++ b/docs/cli.txt @@ -0,0 +1,108 @@ +title: Command Line +prev_title: Library Reference +prev_url: reference.html +next_title: Extensions +next_url: extensions/index.html + + +Using Python-Markdown on the Command Line +========================================= + +While Python-Markdown is primarily a python library, a command line script is +included as well. While there are many other command line implementations +of Markdown, you may not have them installed, or you may prefer to use +Python-Markdown's various extensions. + +Generally, you will want to have the Markdown library fully installed on your +system to run the command line script. See the +[Installation instructions](install.html) for details. + +Assuming the `python` executable is on your system path, just run the following: + + python -m markdown [options] [args] + +That will run the module as a script. Note that on older Python versions (2.5 +and 2.6), you may need to specify the appropriate module: + + python -m markdown.__main__ [options] [args] + +Use the `--help` option for available options: + + python -m markdown --help + +If you are using Python 2.4 or you don't want to have to call the python +executable directly, follow the instructions below: + +Setup +----- + +Upon installation, the ``markdown_py`` script will have been copied to +your Python "Scripts" directory. Different systems require different methods to +ensure that any files in the Python "Scripts" directory are on your system +path. + +* **Windows**: + + Assuming a default install of Python on Windows, your "Scripts" directory + is most likely something like ``C:\\Python26\Scripts``. Verify the location + of your "Scripts" directory and add it to you system path. + + Calling ``markdown_py`` from the command line will call the wrapper batch + file ``markdown_py.bat`` in the "Scripts" directory created during install. + +* __*nix__ (Linux, OSX, BSD, Unix, etc.): + + As each *nix distribution is different and we can't possibly document all + of them here, we'll provide a few helpful pointers: + + * Some systems will automatically install the script on your path. Try it + and see if it works. Just run ``markdown_py`` from the command line. + + * Other systems may maintain a separate "Scripts" directory which you + need to add to your path. Find it (check with your distribution) and + either add it to your path or make a symbolic link to it from your path. + + * If you are sure ``markdown_py`` is on your path, but it still isn't being + found, check the permissions of the file and make sure it is executable. + + As an alternative, you could just ``cd`` into the directory which contains + the source distribution, and run it from there. However, remember that your + markdown text files will not likely be in that directory, so it is much + more convenient to have ``markdown_py`` on your path. + +__Note:__ Python-Markdown uses "markdown_py" as a script name because +the Perl implementation has already taken the more obvious name "markdown". +Additionally, the default Python configuration on some systems would cause a +script named "markdown.py" to fail by importing itself rather than the markdown +library. Therefore, the script has been named "markdown_py" as a compromise. If +you prefer a different name for the script on your system, it is suggested that +you create a symbolic link to `markdown_py` with your preferred name. + +Usage +----- + +To use ``markdown_py`` from the command line, run it as + + $ markdown_py input_file.txt + +or + + $ markdown_py input_file.txt > output_file.html + +For a complete list of options, run + + $ markdown_py --help + +Using Extensions +---------------- + +For an extension to be run from the command line it must be provided in a module +on your python path (see the [Extension API](extensions/api.html) for details). +It can then be invoked by the name of that module: + + $ markdown_py -x footnotes text_with_footnotes.txt > output.html + +If the extension supports config options, you can pass them in as well: + + $ markdown_py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt + diff --git a/docs/extensions/abbreviations.md b/docs/extensions/abbreviations.md deleted file mode 100644 index fa38f50..0000000 --- a/docs/extensions/abbreviations.md +++ /dev/null @@ -1,59 +0,0 @@ -title: Abbreviation Extension -prev_title: Extra Extension -prev_url: extra.html -next_title: Attribute List Extension -next_url: attr_list.html - -Abbreviations -============= - -Summary -------- - -The Markdown Abbreviation Extension adds the ability to define abbreviations. -Specifically, any defined abbreviation is wrapped in an `` 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: - -

The HTML specification - is maintained by the W3C.

- -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/abbreviations.txt b/docs/extensions/abbreviations.txt new file mode 100644 index 0000000..fa38f50 --- /dev/null +++ b/docs/extensions/abbreviations.txt @@ -0,0 +1,59 @@ +title: Abbreviation Extension +prev_title: Extra Extension +prev_url: extra.html +next_title: Attribute List Extension +next_url: attr_list.html + +Abbreviations +============= + +Summary +------- + +The Markdown Abbreviation Extension adds the ability to define abbreviations. +Specifically, any defined abbreviation is wrapped in an `` 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: + +

The HTML specification + is maintained by the W3C.

+ +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/api.md b/docs/extensions/api.md deleted file mode 100644 index 8886b8f..0000000 --- a/docs/extensions/api.md +++ /dev/null @@ -1,612 +0,0 @@ -title: Extensions API -prev_title: Wikilinks Extension -prev_url: wikilinks.html -next_title: Test Suite -next_url: ../test_suite.html - -Writing Extensions for Python-Markdown -====================================== - -Python-Markdown includes an API for extension writers to plug their own -custom functionality and/or syntax into the parser. There are preprocessors -which allow you to alter the source before it is passed to the parser, -inline patterns which allow you to add, remove or override the syntax of -any inline elements, and postprocessors which allow munging of the -output of the parser before it is returned. If you really want to dive in, -there are also blockprocessors which are part of the core BlockParser. - -As the parser builds an [ElementTree][] object which is later rendered -as Unicode text, there are also some helpers provided to ease manipulation of -the tree. Each part of the API is discussed in its respective section below. -Additionally, reading the source of some [Available Extensions][] may be -helpful. For example, the [Footnotes][] extension uses most of the features -documented here. - -Preprocessors {: #preprocessors } ---------------------------------- - -Preprocessors munge the source text before it is passed into the Markdown -core. This is an excellent place to clean up bad syntax, extract things the -parser may otherwise choke on and perhaps even store it for later retrieval. - -Preprocessors should inherit from ``markdown.preprocessors.Preprocessor`` and -implement a ``run`` method with one argument ``lines``. The ``run`` method of -each Preprocessor will be passed the entire source text as a list of Unicode -strings. Each string will contain one line of text. The ``run`` method should -return either that list, or an altered list of Unicode strings. - -A pseudo example: - - from markdown.preprocessors import Preprocessor - - class MyPreprocessor(Preprocessor): - def run(self, lines): - new_lines = [] - for line in lines: - m = MYREGEX.match(line) - if m: - # do stuff - else: - new_lines.append(line) - return new_lines - -Inline Patterns {: #inlinepatterns } ------------------------------------- - -Inline Patterns implement the inline HTML element syntax for Markdown such as -``*emphasis*`` or ``[links](http://example.com)``. Pattern objects should be -instances of classes that inherit from ``markdown.inlinepatterns.Pattern`` or -one of its children. Each pattern object uses a single regular expression and -must have the following methods: - -* **``getCompiledRegExp()``**: - - Returns a compiled regular expression. - -* **``handleMatch(m)``**: - - Accepts a match object and returns an ElementTree element of a plain - Unicode string. - -Note that any regular expression returned by ``getCompiledRegExp`` must capture -the whole block. Therefore, they should all start with ``r'^(.*?)'`` and end -with ``r'(.*?)!'``. When using the default ``getCompiledRegExp()`` method -provided in the ``Pattern`` you can pass in a regular expression without that -and ``getCompiledRegExp`` will wrap your expression for you and set the -`re.DOTALL` and `re.UNICODE` flags. This means that the first group of your -match will be ``m.group(2)`` as ``m.group(1)`` will match everything before the -pattern. - -For an example, consider this simplified emphasis pattern: - - from markdown.inlinepatterns import Pattern - from markdown.util import etree - - class EmphasisPattern(Pattern): - def handleMatch(self, m): - el = etree.Element('em') - el.text = m.group(3) - return el - -As discussed in [Integrating Your Code Into Markdown][], an instance of this -class will need to be provided to Markdown. That instance would be created -like so: - - # an oversimplified regex - MYPATTERN = r'\*([^*]+)\*' - # pass in pattern and create instance - emphasis = EmphasisPattern(MYPATTERN) - -Actually it would not be necessary to create that pattern (and not just because -a more sophisticated emphasis pattern already exists in Markdown). The fact is, -that example pattern is not very DRY. A pattern for `**strong**` text would -be almost identical, with the exception that it would create a 'strong' element. -Therefore, Markdown provides a number of generic pattern classes that can -provide some common functionality. For example, both emphasis and strong are -implemented with separate instances of the ``SimpleTagPettern`` listed below. -Feel free to use or extend any of the Pattern classes found at `markdown.inlinepatterns`. - -**Generic Pattern Classes** - -* **``SimpleTextPattern(pattern)``**: - - Returns simple text of ``group(2)`` of a ``pattern``. - -* **``SimpleTagPattern(pattern, tag)``**: - - Returns an element of type "`tag`" with a text attribute of ``group(3)`` - of a ``pattern``. ``tag`` should be a string of a HTML element (i.e.: 'em'). - -* **``SubstituteTagPattern(pattern, tag)``**: - - Returns an element of type "`tag`" with no children or text (i.e.: 'br'). - -There may be other Pattern classes in the Markdown source that you could extend -or use as well. Read through the source and see if there is anything you can -use. You might even get a few ideas for different approaches to your specific -situation. - -Treeprocessors {: #treeprocessors } ------------------------------------ - -Treeprocessors manipulate an ElemenTree object after it has passed through the -core BlockParser. This is where additional manipulation of the tree takes -place. Additionally, the InlineProcessor is a Treeprocessor which steps through -the tree and runs the InlinePatterns on the text of each Element in the tree. - -A Treeprocessor should inherit from ``markdown.treeprocessors.Treeprocessor``, -over-ride the ``run`` method which takes one argument ``root`` (an Elementree -object) and returns either that root element or a modified root element. - -A pseudo example: - - from markdown.treprocessors import Treeprocessor - - class MyTreeprocessor(Treeprocessor): - def run(self, root): - #do stuff - return my_modified_root - -For specifics on manipulating the ElementTree, see -[Working with the ElementTree][] below. - -Postprocessors {: #postprocessors } ------------------------------------ - -Postprocessors manipulate the document after the ElementTree has been -serialized into a string. Postprocessors should be used to work with the -text just before output. - -A Postprocessor should inherit from ``markdown.postprocessors.Postprocessor`` -and over-ride the ``run`` method which takes one argument ``text`` and returns -a Unicode string. - -Postprocessors are run after the ElementTree has been serialized back into -Unicode text. For example, this may be an appropriate place to add a table of -contents to a document: - - from markdown.postprocessors import Postprocessor - - class TocPostprocessor(Postprocessor): - def run(self, text): - return MYMARKERRE.sub(MyToc, text) - -BlockParser {: #blockparser } ------------------------------ - -Sometimes, pre/tree/postprocessors and Inline Patterns aren't going to do what -you need. Perhaps you want a new type of block type that needs to be integrated -into the core parsing. In such a situation, you can add/change/remove -functionality of the core ``BlockParser``. The BlockParser is composed of a -number of Blockproccessors. The BlockParser steps through each block of text -(split by blank lines) and passes each block to the appropriate Blockprocessor. -That Blockprocessor parses the block and adds it to the ElementTree. The -[Definition Lists][] extension would be a good example of an extension that -adds/modifies Blockprocessors. - -A Blockprocessor should inherit from ``markdown.blockprocessors.BlockProcessor`` -and implement both the ``test`` and ``run`` methods. - -The ``test`` method is used by BlockParser to identify the type of block. -Therefore the ``test`` method must return a boolean value. If the test returns -``True``, then the BlockParser will call that Blockprocessor's ``run`` method. -If it returns ``False``, the BlockParser will move on to the next -BlockProcessor. - -The **``test``** method takes two arguments: - -* **``parent``**: The parent etree Element of the block. This can be useful as - the block may need to be treated differently if it is inside a list, for - example. - -* **``block``**: A string of the current block of text. The test may be a - simple string method (such as ``block.startswith(some_text)``) or a complex - regular expression. - -The **``run``** method takes two arguments: - -* **``parent``**: A pointer to the parent etree Element of the block. The run - method will most likely attach additional nodes to this parent. Note that - nothing is returned by the method. The Elementree object is altered in place. - -* **``blocks``**: A list of all remaining blocks of the document. Your run - method must remove (pop) the first block from the list (which it altered in - place - not returned) and parse that block. You may find that a block of text - legitimately contains multiple block types. Therefore, after processing the - first type, your processor can insert the remaining text into the beginning - of the ``blocks`` list for future parsing. - -Please be aware that a single block can span multiple text blocks. For example, -The official Markdown syntax rules state that a blank line does not end a -Code Block. If the next block of text is also indented, then it is part of -the previous block. Therefore, the BlockParser was specifically designed to -address these types of situations. If you notice the ``CodeBlockProcessor``, -in the core, you will note that it checks the last child of the ``parent``. -If the last child is a code block (``
...
``), then it -appends that block to the previous code block rather than creating a new -code block. - -Each BlockProcessor has the following utility methods available: - -* **``lastChild(parent)``**: - - Returns the last child of the given etree Element or ``None`` if it had no - children. - -* **``detab(text)``**: - - Removes one level of indent (four spaces by default) from the front of each - line of the given text string. - -* **``looseDetab(text, level)``**: - - Removes "level" levels of indent (defaults to 1) from the front of each line - of the given text string. However, this methods allows secondary lines to - not be indented as does some parts of the Markdown syntax. - -Each BlockProcessor also has a pointer to the containing BlockParser instance at -``self.parser``, which can be used to check or alter the state of the parser. -The BlockParser tracks it's state in a stack at ``parser.state``. The state -stack is an instance of the ``State`` class. - -**``State``** is a subclass of ``list`` and has the additional methods: - -* **``set(state)``**: - - Set a new state to string ``state``. The new state is appended to the end - of the stack. - -* **``reset()``**: - - Step back one step in the stack. The last state at the end is removed from - the stack. - -* **``isstate(state)``**: - - Test that the top (current) level of the stack is of the given string - ``state``. - -Note that to ensure that the state stack doesn't become corrupted, each time a -state is set for a block, that state *must* be reset when the parser finishes -parsing that block. - -An instance of the **``BlockParser``** is found at ``Markdown.parser``. -``BlockParser`` has the following methods: - -* **``parseDocument(lines)``**: - - Given a list of lines, an ElementTree object is returned. This should be - passed an entire document and is the only method the ``Markdown`` class - calls directly. - -* **``parseChunk(parent, text)``**: - - Parses a chunk of markdown text composed of multiple blocks and attaches - those blocks to the ``parent`` Element. The ``parent`` is altered in place - and nothing is returned. Extensions would most likely use this method for - block parsing. - -* **``parseBlocks(parent, blocks)``**: - - Parses a list of blocks of text and attaches those blocks to the ``parent`` - Element. The ``parent`` is altered in place and nothing is returned. This - method will generally only be used internally to recursively parse nested - blocks of text. - -While is is not recommended, an extension could subclass or completely replace -the ``BlockParser``. The new class would have to provide the same public API. -However, be aware that other extensions may expect the core parser provided -and will not work with such a drastically different parser. - -Working with the ElementTree {: #working_with_et } --------------------------------------------------- - -As mentioned, the Markdown parser converts a source document to an -[ElementTree][] object before serializing that back to Unicode text. -Markdown has provided some helpers to ease that manipulation within the context -of the Markdown module. - -First, to get access to the ElementTree module import ElementTree from -``markdown`` rather than importing it directly. This will ensure you are using -the same version of ElementTree as markdown. The module is found at -``markdown.util.etree`` within Markdown. - - from markdown.util import etree - -``markdown.util.etree`` tries to import ElementTree from any known location, -first as a standard library module (from ``xml.etree`` in Python 2.5), then as -a third party package (``Elementree``). In each instance, ``cElementTree`` is -tried first, then ``ElementTree`` if the faster C implementation is not -available on your system. - -Sometimes you may want text inserted into an element to be parsed by -[InlinePatterns][]. In such a situation, simply insert the text as you normally -would and the text will be automatically run through the InlinePatterns. -However, if you do *not* want some text to be parsed by InlinePatterns, -then insert the text as an ``AtomicString``. - - from markdown.util import AtomicString - some_element.text = AtomicString(some_text) - -Here's a basic example which creates an HTML table (note that the contents of -the second cell (``td2``) will be run through InlinePatterns latter): - - table = etree.Element("table") - table.set("cellpadding", "2") # Set cellpadding to 2 - tr = etree.SubElement(table, "tr") # Add child tr to table - td1 = etree.SubElement(tr, "td") # Add child td1 to tr - td1.text = markdown.AtomicString("Cell content") # Add plain text content - td2 = etree.SubElement(tr, "td") # Add second td to tr - td2.text = "*text* with **inline** formatting." # Add markup text - table.tail = "Text after table" # Add text after table - -You can also manipulate an existing tree. Consider the following example which -adds a ``class`` attribute to ```` elements: - - def set_link_class(self, element): - for child in element: - if child.tag == "a": - child.set("class", "myclass") #set the class attribute - set_link_class(child) # run recursively on children - -For more information about working with ElementTree see the ElementTree -[Documentation](http://effbot.org/zone/element-index.htm) -([Python Docs](http://docs.python.org/lib/module-xml.etree.ElementTree.html)). - -Integrating Your Code Into Markdown {: #integrating_into_markdown } -------------------------------------------------------------------- - -Once you have the various pieces of your extension built, you need to tell -Markdown about them and ensure that they are run in the proper sequence. -Markdown accepts a ``Extension`` instance for each extension. Therefore, you -will need to define a class that extends ``markdown.extensions.Extension`` and -over-rides the ``extendMarkdown`` method. Within this class you will manage -configuration options for your extension and attach the various processors and -patterns to the Markdown instance. - -It is important to note that the order of the various processors and patterns -matters. For example, if we replace ``http://...`` links with ```` elements, -and *then* try to deal with inline html, we will end up with a mess. -Therefore, the various types of processors and patterns are stored within an -instance of the Markdown class in [OrderedDict][]s. Your ``Extension`` class -will need to manipulate those OrderedDicts appropriately. You may insert -instances of your processors and patterns into the appropriate location in an -OrderedDict, remove a built-in instance, or replace a built-in instance with -your own. - -### extendMarkdown {: #extendmarkdown } - -The ``extendMarkdown`` method of a ``markdown.extensions.Extension`` class -accepts two arguments: - -* **``md``**: - - A pointer to the instance of the Markdown class. You should use this to - access the [OrderedDict][]s of processors and patterns. They are found - under the following attributes: - - * ``md.preprocessors`` - * ``md.inlinePatterns`` - * ``md.parser.blockprocessors`` - * ``md.treepreprocessors`` - * ``md.postprocessors`` - - Some other things you may want to access in the markdown instance are: - - * ``md.htmlStash`` - * ``md.output_formats`` - * ``md.set_output_format()`` - * ``md.registerExtension()`` - * ``md.html_replacement_text`` - * ``md.tab_length`` - * ``md.enable_attributes`` - * ``md.smart_emphasis`` - -* **``md_globals``**: - - Contains all the various global variables within the markdown module. - -Of course, with access to those items, theoretically you have the option to -changing anything through various [monkey_patching][] techniques. However, you -should be aware that the various undocumented or private parts of markdown -may change without notice and your monkey_patches may break with a new release. -Therefore, what you really should be doing is inserting processors and patterns -into the markdown pipeline. Consider yourself warned. - -[monkey_patching]: http://en.wikipedia.org/wiki/Monkey_patch - -A simple example: - - from markdown.extensions import Extension - - class MyExtension(Extension): - def extendMarkdown(self, md, md_globals): - # Insert instance of 'mypattern' before 'references' pattern - md.inlinePatterns.add('mypattern', MyPattern(md), '``) followed by an existing key (i.e.: - ``">somekey"``) inserts that item after the existing key. - -Consider the following example: - - >>> from markdown.odict import OrderedDict - >>> od = OrderedDict() - >>> od['one'] = 1 # The same as: od.add('one', 1, '_begin') - >>> od['three'] = 3 # The same as: od.add('three', 3, '>one') - >>> od['four'] = 4 # The same as: od.add('four', 4, '_end') - >>> od.items() - [("one", 1), ("three", 3), ("four", 4)] - -Note that when building an OrderedDict in order, the extra features of the -``add`` method offer no real value and are not necessary. However, when -manipulating an existing OrderedDict, ``add`` can be very helpful. So let's -insert another item into the OrderedDict. - - >>> od.add('two', 2, '>one') # Insert after 'one' - >>> od.values() - [1, 2, 3, 4] - -Now let's insert another item. - - >>> od.add('twohalf', 2.5, '>> od.keys() - ["one", "two", "twohalf", "three", "four"] - -Note that we also could have set the location of "twohalf" to be 'after two' -(i.e.: ``'>two'``). However, it's unlikely that you will have control over the -order in which extensions will be loaded, and this could affect the final -sorted order of an OrderedDict. For example, suppose an extension adding -'twohalf' in the above examples was loaded before a separate extension which -adds 'two'. You may need to take this into consideration when adding your -extension components to the various markdown OrderedDicts. - -Once an OrderedDict is created, the items are available via key: - - MyNode = od['somekey'] - -Therefore, to delete an existing item: - - del od['somekey'] - -To change the value of an existing item (leaving location unchanged): - - od['somekey'] = MyNewObject() - -To change the location of an existing item: - - t.link('somekey', ' output.txt - -Note that parameters should always be assumed to be set to string -values, and should be converted at run time. For example: - - i = int(self.getConfig("SOME_PARAM")) - -### makeExtension {: #makeextension } - -Each extension should ideally be placed in its own module starting -with the ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must -provide a module-level function called ``makeExtension`` that takes -an optional parameter consisting of a dictionary of configuration over-rides -and returns an instance of the extension. An example from the footnote -extension: - - def makeExtension(configs=None) : - return FootnoteExtension(configs=configs) - -By following the above example, when Markdown is passed the name of your -extension as a string (i.e.: ``'footnotes'``), it will automatically import -the module and call the ``makeExtension`` function initiating your extension. - -You may have noted that the extensions packaged with Python-Markdown do not -use the ``mdx_`` prefix in their module names. This is because they are all -part of the ``markdown.extensions`` package. Markdown will first try to import -from ``markdown.extensions.extname`` and upon failure, ``mdx_extname``. If both -fail, Markdown will continue without the extension. - -However, Markdown will also accept an already existing instance of an extension. -For example: - - import markdown - import myextension - configs = {...} - myext = myextension.MyExtension(configs=configs) - md = markdown.Markdown(extensions=[myext]) - -This is useful if you need to implement a large number of extensions with more -than one residing in a module. - -[Preprocessors]: #preprocessors -[InlinePatterns]: #inlinepatterns -[Treeprocessors]: #treeprocessors -[Postprocessors]: #postprocessors -[BlockParser]: #blockparser -[Working with the ElementTree]: #working_with_et -[Integrating your code into Markdown]: #integrating_into_markdown -[extendMarkdown]: #extendmarkdown -[OrderedDict]: #ordereddict -[registerExtension]: #registerextension -[Config Settings]: #configsettings -[makeExtension]: #makeextension -[ElementTree]: http://effbot.org/zone/element-index.htm -[Available Extensions]: index.html -[Footnotes]: footnotes.html -[Definition Lists]: definition_lists.html diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt new file mode 100644 index 0000000..8886b8f --- /dev/null +++ b/docs/extensions/api.txt @@ -0,0 +1,612 @@ +title: Extensions API +prev_title: Wikilinks Extension +prev_url: wikilinks.html +next_title: Test Suite +next_url: ../test_suite.html + +Writing Extensions for Python-Markdown +====================================== + +Python-Markdown includes an API for extension writers to plug their own +custom functionality and/or syntax into the parser. There are preprocessors +which allow you to alter the source before it is passed to the parser, +inline patterns which allow you to add, remove or override the syntax of +any inline elements, and postprocessors which allow munging of the +output of the parser before it is returned. If you really want to dive in, +there are also blockprocessors which are part of the core BlockParser. + +As the parser builds an [ElementTree][] object which is later rendered +as Unicode text, there are also some helpers provided to ease manipulation of +the tree. Each part of the API is discussed in its respective section below. +Additionally, reading the source of some [Available Extensions][] may be +helpful. For example, the [Footnotes][] extension uses most of the features +documented here. + +Preprocessors {: #preprocessors } +--------------------------------- + +Preprocessors munge the source text before it is passed into the Markdown +core. This is an excellent place to clean up bad syntax, extract things the +parser may otherwise choke on and perhaps even store it for later retrieval. + +Preprocessors should inherit from ``markdown.preprocessors.Preprocessor`` and +implement a ``run`` method with one argument ``lines``. The ``run`` method of +each Preprocessor will be passed the entire source text as a list of Unicode +strings. Each string will contain one line of text. The ``run`` method should +return either that list, or an altered list of Unicode strings. + +A pseudo example: + + from markdown.preprocessors import Preprocessor + + class MyPreprocessor(Preprocessor): + def run(self, lines): + new_lines = [] + for line in lines: + m = MYREGEX.match(line) + if m: + # do stuff + else: + new_lines.append(line) + return new_lines + +Inline Patterns {: #inlinepatterns } +------------------------------------ + +Inline Patterns implement the inline HTML element syntax for Markdown such as +``*emphasis*`` or ``[links](http://example.com)``. Pattern objects should be +instances of classes that inherit from ``markdown.inlinepatterns.Pattern`` or +one of its children. Each pattern object uses a single regular expression and +must have the following methods: + +* **``getCompiledRegExp()``**: + + Returns a compiled regular expression. + +* **``handleMatch(m)``**: + + Accepts a match object and returns an ElementTree element of a plain + Unicode string. + +Note that any regular expression returned by ``getCompiledRegExp`` must capture +the whole block. Therefore, they should all start with ``r'^(.*?)'`` and end +with ``r'(.*?)!'``. When using the default ``getCompiledRegExp()`` method +provided in the ``Pattern`` you can pass in a regular expression without that +and ``getCompiledRegExp`` will wrap your expression for you and set the +`re.DOTALL` and `re.UNICODE` flags. This means that the first group of your +match will be ``m.group(2)`` as ``m.group(1)`` will match everything before the +pattern. + +For an example, consider this simplified emphasis pattern: + + from markdown.inlinepatterns import Pattern + from markdown.util import etree + + class EmphasisPattern(Pattern): + def handleMatch(self, m): + el = etree.Element('em') + el.text = m.group(3) + return el + +As discussed in [Integrating Your Code Into Markdown][], an instance of this +class will need to be provided to Markdown. That instance would be created +like so: + + # an oversimplified regex + MYPATTERN = r'\*([^*]+)\*' + # pass in pattern and create instance + emphasis = EmphasisPattern(MYPATTERN) + +Actually it would not be necessary to create that pattern (and not just because +a more sophisticated emphasis pattern already exists in Markdown). The fact is, +that example pattern is not very DRY. A pattern for `**strong**` text would +be almost identical, with the exception that it would create a 'strong' element. +Therefore, Markdown provides a number of generic pattern classes that can +provide some common functionality. For example, both emphasis and strong are +implemented with separate instances of the ``SimpleTagPettern`` listed below. +Feel free to use or extend any of the Pattern classes found at `markdown.inlinepatterns`. + +**Generic Pattern Classes** + +* **``SimpleTextPattern(pattern)``**: + + Returns simple text of ``group(2)`` of a ``pattern``. + +* **``SimpleTagPattern(pattern, tag)``**: + + Returns an element of type "`tag`" with a text attribute of ``group(3)`` + of a ``pattern``. ``tag`` should be a string of a HTML element (i.e.: 'em'). + +* **``SubstituteTagPattern(pattern, tag)``**: + + Returns an element of type "`tag`" with no children or text (i.e.: 'br'). + +There may be other Pattern classes in the Markdown source that you could extend +or use as well. Read through the source and see if there is anything you can +use. You might even get a few ideas for different approaches to your specific +situation. + +Treeprocessors {: #treeprocessors } +----------------------------------- + +Treeprocessors manipulate an ElemenTree object after it has passed through the +core BlockParser. This is where additional manipulation of the tree takes +place. Additionally, the InlineProcessor is a Treeprocessor which steps through +the tree and runs the InlinePatterns on the text of each Element in the tree. + +A Treeprocessor should inherit from ``markdown.treeprocessors.Treeprocessor``, +over-ride the ``run`` method which takes one argument ``root`` (an Elementree +object) and returns either that root element or a modified root element. + +A pseudo example: + + from markdown.treprocessors import Treeprocessor + + class MyTreeprocessor(Treeprocessor): + def run(self, root): + #do stuff + return my_modified_root + +For specifics on manipulating the ElementTree, see +[Working with the ElementTree][] below. + +Postprocessors {: #postprocessors } +----------------------------------- + +Postprocessors manipulate the document after the ElementTree has been +serialized into a string. Postprocessors should be used to work with the +text just before output. + +A Postprocessor should inherit from ``markdown.postprocessors.Postprocessor`` +and over-ride the ``run`` method which takes one argument ``text`` and returns +a Unicode string. + +Postprocessors are run after the ElementTree has been serialized back into +Unicode text. For example, this may be an appropriate place to add a table of +contents to a document: + + from markdown.postprocessors import Postprocessor + + class TocPostprocessor(Postprocessor): + def run(self, text): + return MYMARKERRE.sub(MyToc, text) + +BlockParser {: #blockparser } +----------------------------- + +Sometimes, pre/tree/postprocessors and Inline Patterns aren't going to do what +you need. Perhaps you want a new type of block type that needs to be integrated +into the core parsing. In such a situation, you can add/change/remove +functionality of the core ``BlockParser``. The BlockParser is composed of a +number of Blockproccessors. The BlockParser steps through each block of text +(split by blank lines) and passes each block to the appropriate Blockprocessor. +That Blockprocessor parses the block and adds it to the ElementTree. The +[Definition Lists][] extension would be a good example of an extension that +adds/modifies Blockprocessors. + +A Blockprocessor should inherit from ``markdown.blockprocessors.BlockProcessor`` +and implement both the ``test`` and ``run`` methods. + +The ``test`` method is used by BlockParser to identify the type of block. +Therefore the ``test`` method must return a boolean value. If the test returns +``True``, then the BlockParser will call that Blockprocessor's ``run`` method. +If it returns ``False``, the BlockParser will move on to the next +BlockProcessor. + +The **``test``** method takes two arguments: + +* **``parent``**: The parent etree Element of the block. This can be useful as + the block may need to be treated differently if it is inside a list, for + example. + +* **``block``**: A string of the current block of text. The test may be a + simple string method (such as ``block.startswith(some_text)``) or a complex + regular expression. + +The **``run``** method takes two arguments: + +* **``parent``**: A pointer to the parent etree Element of the block. The run + method will most likely attach additional nodes to this parent. Note that + nothing is returned by the method. The Elementree object is altered in place. + +* **``blocks``**: A list of all remaining blocks of the document. Your run + method must remove (pop) the first block from the list (which it altered in + place - not returned) and parse that block. You may find that a block of text + legitimately contains multiple block types. Therefore, after processing the + first type, your processor can insert the remaining text into the beginning + of the ``blocks`` list for future parsing. + +Please be aware that a single block can span multiple text blocks. For example, +The official Markdown syntax rules state that a blank line does not end a +Code Block. If the next block of text is also indented, then it is part of +the previous block. Therefore, the BlockParser was specifically designed to +address these types of situations. If you notice the ``CodeBlockProcessor``, +in the core, you will note that it checks the last child of the ``parent``. +If the last child is a code block (``
...
``), then it +appends that block to the previous code block rather than creating a new +code block. + +Each BlockProcessor has the following utility methods available: + +* **``lastChild(parent)``**: + + Returns the last child of the given etree Element or ``None`` if it had no + children. + +* **``detab(text)``**: + + Removes one level of indent (four spaces by default) from the front of each + line of the given text string. + +* **``looseDetab(text, level)``**: + + Removes "level" levels of indent (defaults to 1) from the front of each line + of the given text string. However, this methods allows secondary lines to + not be indented as does some parts of the Markdown syntax. + +Each BlockProcessor also has a pointer to the containing BlockParser instance at +``self.parser``, which can be used to check or alter the state of the parser. +The BlockParser tracks it's state in a stack at ``parser.state``. The state +stack is an instance of the ``State`` class. + +**``State``** is a subclass of ``list`` and has the additional methods: + +* **``set(state)``**: + + Set a new state to string ``state``. The new state is appended to the end + of the stack. + +* **``reset()``**: + + Step back one step in the stack. The last state at the end is removed from + the stack. + +* **``isstate(state)``**: + + Test that the top (current) level of the stack is of the given string + ``state``. + +Note that to ensure that the state stack doesn't become corrupted, each time a +state is set for a block, that state *must* be reset when the parser finishes +parsing that block. + +An instance of the **``BlockParser``** is found at ``Markdown.parser``. +``BlockParser`` has the following methods: + +* **``parseDocument(lines)``**: + + Given a list of lines, an ElementTree object is returned. This should be + passed an entire document and is the only method the ``Markdown`` class + calls directly. + +* **``parseChunk(parent, text)``**: + + Parses a chunk of markdown text composed of multiple blocks and attaches + those blocks to the ``parent`` Element. The ``parent`` is altered in place + and nothing is returned. Extensions would most likely use this method for + block parsing. + +* **``parseBlocks(parent, blocks)``**: + + Parses a list of blocks of text and attaches those blocks to the ``parent`` + Element. The ``parent`` is altered in place and nothing is returned. This + method will generally only be used internally to recursively parse nested + blocks of text. + +While is is not recommended, an extension could subclass or completely replace +the ``BlockParser``. The new class would have to provide the same public API. +However, be aware that other extensions may expect the core parser provided +and will not work with such a drastically different parser. + +Working with the ElementTree {: #working_with_et } +-------------------------------------------------- + +As mentioned, the Markdown parser converts a source document to an +[ElementTree][] object before serializing that back to Unicode text. +Markdown has provided some helpers to ease that manipulation within the context +of the Markdown module. + +First, to get access to the ElementTree module import ElementTree from +``markdown`` rather than importing it directly. This will ensure you are using +the same version of ElementTree as markdown. The module is found at +``markdown.util.etree`` within Markdown. + + from markdown.util import etree + +``markdown.util.etree`` tries to import ElementTree from any known location, +first as a standard library module (from ``xml.etree`` in Python 2.5), then as +a third party package (``Elementree``). In each instance, ``cElementTree`` is +tried first, then ``ElementTree`` if the faster C implementation is not +available on your system. + +Sometimes you may want text inserted into an element to be parsed by +[InlinePatterns][]. In such a situation, simply insert the text as you normally +would and the text will be automatically run through the InlinePatterns. +However, if you do *not* want some text to be parsed by InlinePatterns, +then insert the text as an ``AtomicString``. + + from markdown.util import AtomicString + some_element.text = AtomicString(some_text) + +Here's a basic example which creates an HTML table (note that the contents of +the second cell (``td2``) will be run through InlinePatterns latter): + + table = etree.Element("table") + table.set("cellpadding", "2") # Set cellpadding to 2 + tr = etree.SubElement(table, "tr") # Add child tr to table + td1 = etree.SubElement(tr, "td") # Add child td1 to tr + td1.text = markdown.AtomicString("Cell content") # Add plain text content + td2 = etree.SubElement(tr, "td") # Add second td to tr + td2.text = "*text* with **inline** formatting." # Add markup text + table.tail = "Text after table" # Add text after table + +You can also manipulate an existing tree. Consider the following example which +adds a ``class`` attribute to ```` elements: + + def set_link_class(self, element): + for child in element: + if child.tag == "a": + child.set("class", "myclass") #set the class attribute + set_link_class(child) # run recursively on children + +For more information about working with ElementTree see the ElementTree +[Documentation](http://effbot.org/zone/element-index.htm) +([Python Docs](http://docs.python.org/lib/module-xml.etree.ElementTree.html)). + +Integrating Your Code Into Markdown {: #integrating_into_markdown } +------------------------------------------------------------------- + +Once you have the various pieces of your extension built, you need to tell +Markdown about them and ensure that they are run in the proper sequence. +Markdown accepts a ``Extension`` instance for each extension. Therefore, you +will need to define a class that extends ``markdown.extensions.Extension`` and +over-rides the ``extendMarkdown`` method. Within this class you will manage +configuration options for your extension and attach the various processors and +patterns to the Markdown instance. + +It is important to note that the order of the various processors and patterns +matters. For example, if we replace ``http://...`` links with ```` elements, +and *then* try to deal with inline html, we will end up with a mess. +Therefore, the various types of processors and patterns are stored within an +instance of the Markdown class in [OrderedDict][]s. Your ``Extension`` class +will need to manipulate those OrderedDicts appropriately. You may insert +instances of your processors and patterns into the appropriate location in an +OrderedDict, remove a built-in instance, or replace a built-in instance with +your own. + +### extendMarkdown {: #extendmarkdown } + +The ``extendMarkdown`` method of a ``markdown.extensions.Extension`` class +accepts two arguments: + +* **``md``**: + + A pointer to the instance of the Markdown class. You should use this to + access the [OrderedDict][]s of processors and patterns. They are found + under the following attributes: + + * ``md.preprocessors`` + * ``md.inlinePatterns`` + * ``md.parser.blockprocessors`` + * ``md.treepreprocessors`` + * ``md.postprocessors`` + + Some other things you may want to access in the markdown instance are: + + * ``md.htmlStash`` + * ``md.output_formats`` + * ``md.set_output_format()`` + * ``md.registerExtension()`` + * ``md.html_replacement_text`` + * ``md.tab_length`` + * ``md.enable_attributes`` + * ``md.smart_emphasis`` + +* **``md_globals``**: + + Contains all the various global variables within the markdown module. + +Of course, with access to those items, theoretically you have the option to +changing anything through various [monkey_patching][] techniques. However, you +should be aware that the various undocumented or private parts of markdown +may change without notice and your monkey_patches may break with a new release. +Therefore, what you really should be doing is inserting processors and patterns +into the markdown pipeline. Consider yourself warned. + +[monkey_patching]: http://en.wikipedia.org/wiki/Monkey_patch + +A simple example: + + from markdown.extensions import Extension + + class MyExtension(Extension): + def extendMarkdown(self, md, md_globals): + # Insert instance of 'mypattern' before 'references' pattern + md.inlinePatterns.add('mypattern', MyPattern(md), '``) followed by an existing key (i.e.: + ``">somekey"``) inserts that item after the existing key. + +Consider the following example: + + >>> from markdown.odict import OrderedDict + >>> od = OrderedDict() + >>> od['one'] = 1 # The same as: od.add('one', 1, '_begin') + >>> od['three'] = 3 # The same as: od.add('three', 3, '>one') + >>> od['four'] = 4 # The same as: od.add('four', 4, '_end') + >>> od.items() + [("one", 1), ("three", 3), ("four", 4)] + +Note that when building an OrderedDict in order, the extra features of the +``add`` method offer no real value and are not necessary. However, when +manipulating an existing OrderedDict, ``add`` can be very helpful. So let's +insert another item into the OrderedDict. + + >>> od.add('two', 2, '>one') # Insert after 'one' + >>> od.values() + [1, 2, 3, 4] + +Now let's insert another item. + + >>> od.add('twohalf', 2.5, '>> od.keys() + ["one", "two", "twohalf", "three", "four"] + +Note that we also could have set the location of "twohalf" to be 'after two' +(i.e.: ``'>two'``). However, it's unlikely that you will have control over the +order in which extensions will be loaded, and this could affect the final +sorted order of an OrderedDict. For example, suppose an extension adding +'twohalf' in the above examples was loaded before a separate extension which +adds 'two'. You may need to take this into consideration when adding your +extension components to the various markdown OrderedDicts. + +Once an OrderedDict is created, the items are available via key: + + MyNode = od['somekey'] + +Therefore, to delete an existing item: + + del od['somekey'] + +To change the value of an existing item (leaving location unchanged): + + od['somekey'] = MyNewObject() + +To change the location of an existing item: + + t.link('somekey', ' output.txt + +Note that parameters should always be assumed to be set to string +values, and should be converted at run time. For example: + + i = int(self.getConfig("SOME_PARAM")) + +### makeExtension {: #makeextension } + +Each extension should ideally be placed in its own module starting +with the ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must +provide a module-level function called ``makeExtension`` that takes +an optional parameter consisting of a dictionary of configuration over-rides +and returns an instance of the extension. An example from the footnote +extension: + + def makeExtension(configs=None) : + return FootnoteExtension(configs=configs) + +By following the above example, when Markdown is passed the name of your +extension as a string (i.e.: ``'footnotes'``), it will automatically import +the module and call the ``makeExtension`` function initiating your extension. + +You may have noted that the extensions packaged with Python-Markdown do not +use the ``mdx_`` prefix in their module names. This is because they are all +part of the ``markdown.extensions`` package. Markdown will first try to import +from ``markdown.extensions.extname`` and upon failure, ``mdx_extname``. If both +fail, Markdown will continue without the extension. + +However, Markdown will also accept an already existing instance of an extension. +For example: + + import markdown + import myextension + configs = {...} + myext = myextension.MyExtension(configs=configs) + md = markdown.Markdown(extensions=[myext]) + +This is useful if you need to implement a large number of extensions with more +than one residing in a module. + +[Preprocessors]: #preprocessors +[InlinePatterns]: #inlinepatterns +[Treeprocessors]: #treeprocessors +[Postprocessors]: #postprocessors +[BlockParser]: #blockparser +[Working with the ElementTree]: #working_with_et +[Integrating your code into Markdown]: #integrating_into_markdown +[extendMarkdown]: #extendmarkdown +[OrderedDict]: #ordereddict +[registerExtension]: #registerextension +[Config Settings]: #configsettings +[makeExtension]: #makeextension +[ElementTree]: http://effbot.org/zone/element-index.htm +[Available Extensions]: index.html +[Footnotes]: footnotes.html +[Definition Lists]: definition_lists.html diff --git a/docs/extensions/attr_list.md b/docs/extensions/attr_list.md deleted file mode 100644 index 11c6a28..0000000 --- a/docs/extensions/attr_list.md +++ /dev/null @@ -1,80 +0,0 @@ -title: Attribute List Extension -prev_title: Abbreviation Extension -prev_url: abbreviations.html -next_title: Definition List Extension -next_url: definition_lists.html - -Attribute Lists -=============== - -Summary -------- - -An extension to Python-Markdown that adds a syntax to define attributes on -the various HTML elements in markdown's output. - -This extension is included in the standard Markdown library. - -Syntax ------- - -The basic syntax was inspired by [Maruku][]'s Attribute List feature. - -[Maruku]: http://maruku.rubyforge.org/proposal.html#attribute_lists - -### The List ### - -An example attribute list might look like this: - - {: #someid .someclass somekey='some values' } - -A word which starts with a hash `#` will set the id of an element. - -A word which starts with a dot `.` will add to the list of classes assigned to -an element. - -A key/value pair will assign that pair to the element. - -Be aware that while the dot syntax will add to a class, using key/value pairs -will always override the previously defined attribute. Consider the following: - - {: #id1 .class1 id=id2 class="class2 class3" .class4 } - -The above example would result in the following attributes being defined: - - id="id2 class="class2 class3 class4" - -### Block Level ### - -To define attributes for a block level element, the attribute list should -be defined on the last line of the block by itself. - - This is a paragraph. - {: #an_id .a_class } - -The above results in the following output: - -

This is a paragraph.

- -The one exception is headers, as they are only ever allowed on one line. - - A setext style header {: #setext} - ================================= - - ### A hash style header ### {: #hash } - -The above results in the following output: - -

A setext style header

-

A hash style header

- -### Inline ### - -To define attributes on inline elements, the attribute list should be defined -immediately after the inline element with no whitespace. - - [link](http://example.com){: class="foo bar" title="Some title! } - -The above results in the following output: - -

link

diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt new file mode 100644 index 0000000..11c6a28 --- /dev/null +++ b/docs/extensions/attr_list.txt @@ -0,0 +1,80 @@ +title: Attribute List Extension +prev_title: Abbreviation Extension +prev_url: abbreviations.html +next_title: Definition List Extension +next_url: definition_lists.html + +Attribute Lists +=============== + +Summary +------- + +An extension to Python-Markdown that adds a syntax to define attributes on +the various HTML elements in markdown's output. + +This extension is included in the standard Markdown library. + +Syntax +------ + +The basic syntax was inspired by [Maruku][]'s Attribute List feature. + +[Maruku]: http://maruku.rubyforge.org/proposal.html#attribute_lists + +### The List ### + +An example attribute list might look like this: + + {: #someid .someclass somekey='some values' } + +A word which starts with a hash `#` will set the id of an element. + +A word which starts with a dot `.` will add to the list of classes assigned to +an element. + +A key/value pair will assign that pair to the element. + +Be aware that while the dot syntax will add to a class, using key/value pairs +will always override the previously defined attribute. Consider the following: + + {: #id1 .class1 id=id2 class="class2 class3" .class4 } + +The above example would result in the following attributes being defined: + + id="id2 class="class2 class3 class4" + +### Block Level ### + +To define attributes for a block level element, the attribute list should +be defined on the last line of the block by itself. + + This is a paragraph. + {: #an_id .a_class } + +The above results in the following output: + +

This is a paragraph.

+ +The one exception is headers, as they are only ever allowed on one line. + + A setext style header {: #setext} + ================================= + + ### A hash style header ### {: #hash } + +The above results in the following output: + +

A setext style header

+

A hash style header

+ +### Inline ### + +To define attributes on inline elements, the attribute list should be defined +immediately after the inline element with no whitespace. + + [link](http://example.com){: class="foo bar" title="Some title! } + +The above results in the following output: + +

link

diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md deleted file mode 100644 index aa0fe57..0000000 --- a/docs/extensions/code_hilite.md +++ /dev/null @@ -1,126 +0,0 @@ -title: CodeHilite Extension -prev_title: Smart Strong Extension -prev_url: smart_strong.html -next_title: HTML Tidy Extension -next_url: html_tidy.html - -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 -`
` 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:
-
-    
# Code goes here ...
-    

-
-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)']
-    ... )
-
-If you want to prevent Pygments from guessing the language, only highlighting
-blocks when you explicitly request it, set the `guess_lang` setting to 'False'.
-
-    >>> html = markdown.markdown(text,
-    ...     ['codehilite(guess_lang=False)']
-    ... )
diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
new file mode 100644
index 0000000..aa0fe57
--- /dev/null
+++ b/docs/extensions/code_hilite.txt
@@ -0,0 +1,126 @@
+title:      CodeHilite Extension
+prev_title: Smart Strong Extension
+prev_url:   smart_strong.html
+next_title: HTML Tidy Extension
+next_url:   html_tidy.html
+
+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 
+`
` 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:
+
+    
# Code goes here ...
+    

+
+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)']
+    ... )
+
+If you want to prevent Pygments from guessing the language, only highlighting
+blocks when you explicitly request it, set the `guess_lang` setting to 'False'.
+
+    >>> html = markdown.markdown(text,
+    ...     ['codehilite(guess_lang=False)']
+    ... )
diff --git a/docs/extensions/definition_lists.md b/docs/extensions/definition_lists.md
deleted file mode 100644
index 53f14a0..0000000
--- a/docs/extensions/definition_lists.md
+++ /dev/null
@@ -1,61 +0,0 @@
-title:      Definition List Extension
-prev_title: Attribute List Extension
-prev_url:   attr_list.html
-next_title: Fenced Code Block Extension
-next_url:   fenced_code_blocks.html
-
-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:
-
-    

-    
Apple

-    
Pomaceous fruit of plants of the genus Malus in 
-    the family Rosaceae.

-
-    
Orange

-    
The fruit of an evergreen tree of the genus Citrus.

-    

-
-
-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/definition_lists.txt b/docs/extensions/definition_lists.txt
new file mode 100644
index 0000000..53f14a0
--- /dev/null
+++ b/docs/extensions/definition_lists.txt
@@ -0,0 +1,61 @@
+title:      Definition List Extension
+prev_title: Attribute List Extension
+prev_url:   attr_list.html
+next_title: Fenced Code Block Extension
+next_url:   fenced_code_blocks.html
+
+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:
+
+    

+    
Apple

+    
Pomaceous fruit of plants of the genus Malus in 
+    the family Rosaceae.

+
+    
Orange

+    
The fruit of an evergreen tree of the genus Citrus.

+    

+
+
+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/extra.md b/docs/extensions/extra.md
deleted file mode 100644
index adafe07..0000000
--- a/docs/extensions/extra.md
+++ /dev/null
@@ -1,48 +0,0 @@
-title:      Extra Extension
-prev_title: Extensions
-prev_url:   index.html
-next_title: Abreviation Extension
-next_url:   abbreviations.html
-
-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](abbreviations.html)
-* [Attribute Lists](attr_list.html)
-* [Definition Lists](definition_lists.html)
-* [Fenced Code Blocks](fenced_code_blocks.html)
-* [Footnotes](footnotes.html)
-* [Tables](tables.html)
-* [Smart Strong](smart_strong.html)
-
-See each individual extension for syntax documentation. Extra and all its 
-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](index.html) that are distributed with
-Python-Markdown that are not included here in Extra. The features 
-of 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 the [Extension API](api.html)).  
diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt
new file mode 100644
index 0000000..adafe07
--- /dev/null
+++ b/docs/extensions/extra.txt
@@ -0,0 +1,48 @@
+title:      Extra Extension
+prev_title: Extensions
+prev_url:   index.html
+next_title: Abreviation Extension
+next_url:   abbreviations.html
+
+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](abbreviations.html)
+* [Attribute Lists](attr_list.html)
+* [Definition Lists](definition_lists.html)
+* [Fenced Code Blocks](fenced_code_blocks.html)
+* [Footnotes](footnotes.html)
+* [Tables](tables.html)
+* [Smart Strong](smart_strong.html)
+
+See each individual extension for syntax documentation. Extra and all its 
+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](index.html) that are distributed with
+Python-Markdown that are not included here in Extra. The features 
+of 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 the [Extension API](api.html)).  
diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md
deleted file mode 100644
index 0aa0d34..0000000
--- a/docs/extensions/fenced_code_blocks.md
+++ /dev/null
@@ -1,69 +0,0 @@
-title:      Fenced Code Block Extension
-prev_title: Definition List Extension
-prev_url:   definition_lists.html
-next_title: Footnotes Extension
-next_url:   footnotes.html
-
-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 ```` 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
-    
HTML Document

-    ~~~~
-
-The above will output:
-
-    
# python code
-    

-    
-    
<p>HTML Document</p>
-    

-
-Usage
------
-
-From the Python interpreter:
-
-    >>> html = markdown.markdown(text, ['fenced_code'])
-
-
-
diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.txt
new file mode 100644
index 0000000..0aa0d34
--- /dev/null
+++ b/docs/extensions/fenced_code_blocks.txt
@@ -0,0 +1,69 @@
+title:      Fenced Code Block Extension
+prev_title: Definition List Extension
+prev_url:   definition_lists.html
+next_title: Footnotes Extension
+next_url:   footnotes.html
+
+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 ```` 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
+    
HTML Document

+    ~~~~
+
+The above will output:
+
+    
# python code
+    

+    
+    
<p>HTML Document</p>
+    

+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> html = markdown.markdown(text, ['fenced_code'])
+
+
+
diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md
deleted file mode 100644
index 1d6593c..0000000
--- a/docs/extensions/footnotes.md
+++ /dev/null
@@ -1,68 +0,0 @@
-title:      Footnotes Extension
-prev_title: Fenced Code Block Extension
-prev_url:   fenced_code_blocks.html
-next_title: Tables Extension
-next_url:   tables.html
-
-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/footnotes.txt b/docs/extensions/footnotes.txt
new file mode 100644
index 0000000..1d6593c
--- /dev/null
+++ b/docs/extensions/footnotes.txt
@@ -0,0 +1,68 @@
+title:      Footnotes Extension
+prev_title: Fenced Code Block Extension
+prev_url:   fenced_code_blocks.html
+next_title: Tables Extension
+next_url:   tables.html
+
+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/header_id.md b/docs/extensions/header_id.md
deleted file mode 100644
index 255d35c..0000000
--- a/docs/extensions/header_id.md
+++ /dev/null
@@ -1,111 +0,0 @@
-title:      HeaderId Extension
-prev_title: HTML Tidy Extension
-prev_url:   html_tidy.html
-next_title: Meta-Data Extension
-next_url:   meta_data.html
-
-HeaderId
-========
-
-Summary
--------
-
-An extension to Python-Markdown that automatically generates 'id' attributes
-for HTML header elements (h1-h6) in markdown's output.
-
-This extension is included in the standard Markdown library.
-
-Syntax
-------
-
-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
-    #Header
-    #Header
-
-Results in:
-
-    
Header

-    
Header

-    
Header

-
-Configuring the Output
-----------------------
-
-The HeaderId extension has four configuration settings:
-
-* **level**: Base level for headers.
-
-    Default: `1`
-
-    The `level` setting allows you to automatically adjust the header levels to
-    fit within the hierarchy of your html templates. For example, suppose the 
-    markdown text for a page should not contain any headers higher than level 3
-    (`
`). The following will accomplish that:
-
-        >>>  text = '''
-        ... #Some Header
-        ... ## Next Level'''
-        >>> html = markdown.markdown(text, extensions=['headerid(level=3)'])
-        >>> print html
-        
Some Header

-        
Next Level
'
-
-* **forceid**: Force all headers to have an id.
-
-    Default: `True`
-
-    The `forceid` setting turns on or off the automatically generated ids for 
-    headers that do not have one explicitly defined (using the attr_list 
-    extension).
-
-        >>> text = '''
-        ... # Some Header
-        ... # Header with ID # { #foo }'''
-        >>> html = markdown.markdown(text, 
-                        extensions=['attr_list', 'headerid(forceid=False)'])
-        >>> print html
-        
Some Header

-        
Header with ID

-
-* **separator**: Word separator. Character which replaces whitespace in id.
-
-    Default: `-`
-
-* **slugify**: Callable to generate anchors.
-
-    Default: `markdown.extensions.headerid.slugify`
-
-    If you would like to use a different algorithm to define the ids, you can
-    pass in a callable which takes two arguments:
-
-    * `value`: The string to slugify.
-    * `separator`: The Word Separator.
-
-Using with Meta-Data
---------------------
-
-The HeaderId 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:
-
-* `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:
-
-    
A Header

diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.txt
new file mode 100644
index 0000000..255d35c
--- /dev/null
+++ b/docs/extensions/header_id.txt
@@ -0,0 +1,111 @@
+title:      HeaderId Extension
+prev_title: HTML Tidy Extension
+prev_url:   html_tidy.html
+next_title: Meta-Data Extension
+next_url:   meta_data.html
+
+HeaderId
+========
+
+Summary
+-------
+
+An extension to Python-Markdown that automatically generates 'id' attributes
+for HTML header elements (h1-h6) in markdown's output.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+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
+    #Header
+    #Header
+
+Results in:
+
+    
Header

+    
Header

+    
Header

+
+Configuring the Output
+----------------------
+
+The HeaderId extension has four configuration settings:
+
+* **level**: Base level for headers.
+
+    Default: `1`
+
+    The `level` setting allows you to automatically adjust the header levels to
+    fit within the hierarchy of your html templates. For example, suppose the 
+    markdown text for a page should not contain any headers higher than level 3
+    (`
`). The following will accomplish that:
+
+        >>>  text = '''
+        ... #Some Header
+        ... ## Next Level'''
+        >>> html = markdown.markdown(text, extensions=['headerid(level=3)'])
+        >>> print html
+        
Some Header

+        
Next Level
'
+
+* **forceid**: Force all headers to have an id.
+
+    Default: `True`
+
+    The `forceid` setting turns on or off the automatically generated ids for 
+    headers that do not have one explicitly defined (using the attr_list 
+    extension).
+
+        >>> text = '''
+        ... # Some Header
+        ... # Header with ID # { #foo }'''
+        >>> html = markdown.markdown(text, 
+                        extensions=['attr_list', 'headerid(forceid=False)'])
+        >>> print html
+        
Some Header

+        
Header with ID

+
+* **separator**: Word separator. Character which replaces whitespace in id.
+
+    Default: `-`
+
+* **slugify**: Callable to generate anchors.
+
+    Default: `markdown.extensions.headerid.slugify`
+
+    If you would like to use a different algorithm to define the ids, you can
+    pass in a callable which takes two arguments:
+
+    * `value`: The string to slugify.
+    * `separator`: The Word Separator.
+
+Using with Meta-Data
+--------------------
+
+The HeaderId 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:
+
+* `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:
+
+    
A Header

diff --git a/docs/extensions/html_tidy.md b/docs/extensions/html_tidy.md
deleted file mode 100644
index 391349b..0000000
--- a/docs/extensions/html_tidy.md
+++ /dev/null
@@ -1,34 +0,0 @@
-title:      HTML Tidy Extension
-prev_title: CodeHilite Extension
-prev_url:   code_hilite.html
-next_title: HeaderId Extension
-next_url:   header_id.html
-
-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 
-```` and ```` 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
-[extension configs]: ../reference.html#extension_configs
-
-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/html_tidy.txt b/docs/extensions/html_tidy.txt
new file mode 100644
index 0000000..391349b
--- /dev/null
+++ b/docs/extensions/html_tidy.txt
@@ -0,0 +1,34 @@
+title:      HTML Tidy Extension
+prev_title: CodeHilite Extension
+prev_url:   code_hilite.html
+next_title: HeaderId Extension
+next_url:   header_id.html
+
+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 
+```` and ```` 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
+[extension configs]: ../reference.html#extension_configs
+
+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/index.md b/docs/extensions/index.md
deleted file mode 100644
index 82b0eda..0000000
--- a/docs/extensions/index.md
+++ /dev/null
@@ -1,63 +0,0 @@
-title:      Extensions
-prev_title: Command Line
-prev_url:   ../cli.html
-next_title: Extra Extension
-next_url:   extra.html
-
-
-Available Extensions
-====================
-
-Python Markdown offers a flexible extension mechanism, which makes it possible 
-to change and/or extend the behavior of the parser without having to edit the 
-actual source files. 
-
-To use an extension, pass it's name to markdown with the `extensions` keyword.
-See the [Library Reference](../reference.html#extensions) for more details. 
-
-    markdown.markdown(some_text, extensions=['extra', 'nl2br'])
-
-From the command line, specify an extension with the `-x` option. See the 
-[Command Line docs](../cli.html) or use the `--help` option for more details.
-
-    python -m markdown -x extra input.txt > output.html
-
-Officially Supported Extensions
--------------------------------
-
-The extensions listed below are included with (at least) the most recent release
-and are officially supported by Python-Markdown. 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](extra.html)
-    * [Abbreviations](abbreviations.html)
-    * [Attribute Lists](attr_list.html)
-    * [Definition Lists](definition_lists.html)
-    * [Fenced Code Blocks](fenced_code_blocks.html)
-    * [Footnotes](footnotes.html)
-    * [Tables](tables.html)
-    * [Smart Strong](smart_strong.html)
-* [CodeHilite](code_hilite.html)
-* [HTML Tidy](html_tidy.html)
-* [HeaderId](header_id.html)
-* [Meta-Data](meta_data.html)
-* [New Line to Break](nl2br.html)
-* [RSS](rss.html)
-* [Sane Lists](sane_lists.html)
-* [Table of Contents](toc.html)
-* [WikiLinks](wikilinks.html)
-
-Third Party Extensions
-----------------------
-
-Various individuals and/or organizations have developed extensions which they
-have made available to the public.  A [list of third party 
-extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions)
-is maintained on the wiki for your convenience. The Python-Markdown team 
-offers no official support for these extensions. Please see the developer of 
-each extension for support.
-
-If you would like to write your own extensions, see the 
-[Extensions API](api.html) for details.
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
new file mode 100644
index 0000000..82b0eda
--- /dev/null
+++ b/docs/extensions/index.txt
@@ -0,0 +1,63 @@
+title:      Extensions
+prev_title: Command Line
+prev_url:   ../cli.html
+next_title: Extra Extension
+next_url:   extra.html
+
+
+Available Extensions
+====================
+
+Python Markdown offers a flexible extension mechanism, which makes it possible 
+to change and/or extend the behavior of the parser without having to edit the 
+actual source files. 
+
+To use an extension, pass it's name to markdown with the `extensions` keyword.
+See the [Library Reference](../reference.html#extensions) for more details. 
+
+    markdown.markdown(some_text, extensions=['extra', 'nl2br'])
+
+From the command line, specify an extension with the `-x` option. See the 
+[Command Line docs](../cli.html) or use the `--help` option for more details.
+
+    python -m markdown -x extra input.txt > output.html
+
+Officially Supported Extensions
+-------------------------------
+
+The extensions listed below are included with (at least) the most recent release
+and are officially supported by Python-Markdown. 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](extra.html)
+    * [Abbreviations](abbreviations.html)
+    * [Attribute Lists](attr_list.html)
+    * [Definition Lists](definition_lists.html)
+    * [Fenced Code Blocks](fenced_code_blocks.html)
+    * [Footnotes](footnotes.html)
+    * [Tables](tables.html)
+    * [Smart Strong](smart_strong.html)
+* [CodeHilite](code_hilite.html)
+* [HTML Tidy](html_tidy.html)
+* [HeaderId](header_id.html)
+* [Meta-Data](meta_data.html)
+* [New Line to Break](nl2br.html)
+* [RSS](rss.html)
+* [Sane Lists](sane_lists.html)
+* [Table of Contents](toc.html)
+* [WikiLinks](wikilinks.html)
+
+Third Party Extensions
+----------------------
+
+Various individuals and/or organizations have developed extensions which they
+have made available to the public.  A [list of third party 
+extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions)
+is maintained on the wiki for your convenience. The Python-Markdown team 
+offers no official support for these extensions. Please see the developer of 
+each extension for support.
+
+If you would like to write your own extensions, see the 
+[Extensions API](api.html) for details.
diff --git a/docs/extensions/meta_data.md b/docs/extensions/meta_data.md
deleted file mode 100644
index 1695d8b..0000000
--- a/docs/extensions/meta_data.md
+++ /dev/null
@@ -1,94 +0,0 @@
-title:      Meta-Data Extension
-prev_title: HeaderId Extension
-prev_url:   header_id.html
-next_title: New Line to Break Extension
-next_url:   nl2br.html
-
-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
-    
This is the first paragraph of the document.

-
-    >>> # 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_id.html)
-    * `header_level`
-    * `header_forceid`
-* [WikiLinks](wikilinks.html)
-    * `wiki_base_url`
-    * `wiki_end_url`
-    * `wiki_html_class`
-
diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.txt
new file mode 100644
index 0000000..1695d8b
--- /dev/null
+++ b/docs/extensions/meta_data.txt
@@ -0,0 +1,94 @@
+title:      Meta-Data Extension
+prev_title: HeaderId Extension
+prev_url:   header_id.html
+next_title: New Line to Break Extension
+next_url:   nl2br.html
+
+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
+    
This is the first paragraph of the document.

+
+    >>> # 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_id.html)
+    * `header_level`
+    * `header_forceid`
+* [WikiLinks](wikilinks.html)
+    * `wiki_base_url`
+    * `wiki_end_url`
+    * `wiki_html_class`
+
diff --git a/docs/extensions/nl2br.md b/docs/extensions/nl2br.md
deleted file mode 100644
index affd8ee..0000000
--- a/docs/extensions/nl2br.md
+++ /dev/null
@@ -1,25 +0,0 @@
-title:      New Line to Break Extension
-prev_title: Meta-Data Extension
-prev_url:   meta_data.html
-next_title: RSS Extension
-next_url:   rss.html
-
-NL2BR Extension
-===============
-
-A Python-Markdown extension to treat newlines as hard breaks; like
-StackOverflow and [GitHub][] flavored Markdown do.
-
-Usage:
-
-    >>> import markdown
-    >>> text = """
-    ... Line 1
-    ... Line 2
-    ... """
-    >>> html = markdown.markdown(text, extensions=['nl2br'])
-    >>> print html
-    
Line 1

-    Line 2

-
-[Github]: http://github.github.com/github-flavored-markdown/
diff --git a/docs/extensions/nl2br.txt b/docs/extensions/nl2br.txt
new file mode 100644
index 0000000..affd8ee
--- /dev/null
+++ b/docs/extensions/nl2br.txt
@@ -0,0 +1,25 @@
+title:      New Line to Break Extension
+prev_title: Meta-Data Extension
+prev_url:   meta_data.html
+next_title: RSS Extension
+next_url:   rss.html
+
+NL2BR Extension
+===============
+
+A Python-Markdown extension to treat newlines as hard breaks; like
+StackOverflow and [GitHub][] flavored Markdown do.
+
+Usage:
+
+    >>> import markdown
+    >>> text = """
+    ... Line 1
+    ... Line 2
+    ... """
+    >>> html = markdown.markdown(text, extensions=['nl2br'])
+    >>> print html
+    
Line 1

+    Line 2

+
+[Github]: http://github.github.com/github-flavored-markdown/
diff --git a/docs/extensions/rss.md b/docs/extensions/rss.md
deleted file mode 100644
index 67e6d96..0000000
--- a/docs/extensions/rss.md
+++ /dev/null
@@ -1,41 +0,0 @@
-title:      RSS Extension
-prev_title: New Line to Break Extension
-prev_url:   nl2br.html
-next_title: Sane Lists Extension
-next_url:   sane_lists.html
-
-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/rss.txt b/docs/extensions/rss.txt
new file mode 100644
index 0000000..67e6d96
--- /dev/null
+++ b/docs/extensions/rss.txt
@@ -0,0 +1,41 @@
+title:      RSS Extension
+prev_title: New Line to Break Extension
+prev_url:   nl2br.html
+next_title: Sane Lists Extension
+next_url:   sane_lists.html
+
+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/sane_lists.md b/docs/extensions/sane_lists.md
deleted file mode 100644
index e6c73f4..0000000
--- a/docs/extensions/sane_lists.md
+++ /dev/null
@@ -1,81 +0,0 @@
-title:      Sane Lists Extension
-prev_title: RSS Extension
-prev_url:   rss.html
-next_title: Table of Contents Extension
-next_url:   toc.html
-
-Sane Lists
-==========
-
-Summary
--------
-
-The Sane Lists Extension alters the behavior of the Markdown List syntax
-to be less surprising.
-
-This extension is included in the standard Markdown library.
-
-Syntax
-------
-
-Sane Lists do not allow the mixing of list types. In other words, an ordered
-list will not continue when an unordered list item is encountered and
-vice versa. For example:
-
-    1. Ordered item 1
-    2. Ordered item 2
-
-    * Unordered item 1
-    * Unordered item 2
-
-will result in the following output:
-
-    
    
-      
  1. Ordered item 1
    2. 
-      
  2. Ordered item 2
    3. 
-    

-
-    
    
-      
  • Unordered item 1
    • 
-      
  • Unordered item 2
    • 
-    

-
-Whereas the default Markdown behavior would be to generate an unordered list.
-
-Note that, unlike the default Markdown behavior, if a blank line is not
-included between list items, the different list type is ignored completely. 
-This corresponds to the behavior of paragraphs. For example:
-
-    A Paragraph.
-    * Not a list item.
-
-    1. Ordered list item.
-    * Not a separate list item.
-
-With this extension the above will result in the following output:
-
-    
A Paragraph.
-    * Not a list item.

-
-    
    
-      
  1. Ordered list item.
-      * Not a separate list item.
    2. 
-    

-
-In all other ways, Sane Lists should behave as normal Markdown lists.
-
-Usage
------
-
-From the Python interpreter:
-
-    >>> html = markdown.markdown(text, ['sane_lists'])
-
-To use with other extensions, just add them to the list, like this:
-
-    >>> html = markdown.markdown(text, ['def_list', 'sane_lists'])
-
-The extension can also be called from the command line using Markdown's `-x` 
-parameter:
-
-    python -m markdown -x sane_lists source.txt > output.html
diff --git a/docs/extensions/sane_lists.txt b/docs/extensions/sane_lists.txt
new file mode 100644
index 0000000..e6c73f4
--- /dev/null
+++ b/docs/extensions/sane_lists.txt
@@ -0,0 +1,81 @@
+title:      Sane Lists Extension
+prev_title: RSS Extension
+prev_url:   rss.html
+next_title: Table of Contents Extension
+next_url:   toc.html
+
+Sane Lists
+==========
+
+Summary
+-------
+
+The Sane Lists Extension alters the behavior of the Markdown List syntax
+to be less surprising.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+Sane Lists do not allow the mixing of list types. In other words, an ordered
+list will not continue when an unordered list item is encountered and
+vice versa. For example:
+
+    1. Ordered item 1
+    2. Ordered item 2
+
+    * Unordered item 1
+    * Unordered item 2
+
+will result in the following output:
+
+    
    
+      
  1. Ordered item 1
    2. 
+      
  2. Ordered item 2
    3. 
+    

+
+    
    
+      
  • Unordered item 1
    • 
+      
  • Unordered item 2
    • 
+    

+
+Whereas the default Markdown behavior would be to generate an unordered list.
+
+Note that, unlike the default Markdown behavior, if a blank line is not
+included between list items, the different list type is ignored completely. 
+This corresponds to the behavior of paragraphs. For example:
+
+    A Paragraph.
+    * Not a list item.
+
+    1. Ordered list item.
+    * Not a separate list item.
+
+With this extension the above will result in the following output:
+
+    
A Paragraph.
+    * Not a list item.

+
+    
    
+      
  1. Ordered list item.
+      * Not a separate list item.
    2. 
+    

+
+In all other ways, Sane Lists should behave as normal Markdown lists.
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> html = markdown.markdown(text, ['sane_lists'])
+
+To use with other extensions, just add them to the list, like this:
+
+    >>> html = markdown.markdown(text, ['def_list', 'sane_lists'])
+
+The extension can also be called from the command line using Markdown's `-x` 
+parameter:
+
+    python -m markdown -x sane_lists source.txt > output.html
diff --git a/docs/extensions/smart_strong.md b/docs/extensions/smart_strong.md
deleted file mode 100644
index 8de574f..0000000
--- a/docs/extensions/smart_strong.md
+++ /dev/null
@@ -1,37 +0,0 @@
-title:      Smart Strong Extension
-prev_title: Tables Extension
-prev_url:   tables.html
-next_title: CodeHilite Extension
-next_url:   code_hilite.html
-
-Smart_Strong
-============
-
-Summary
--------
-
-The Markdown Smart_Strong Extension adds smarter handling of double underscores
-within words. This does for double underscores what 
-[smart_emphasis](../reference.html#smart_emphasis) does for single underscores.
-
-The Smart_Strong Extension is included in the standard Markdown library.
-
-Usage
------
-
-    >>> import markdown
-    >>> markdown.markdown('Text with double__underscore__words.', \
-                          extensions=['smart_strong'])
-    u'
Text with double__underscore__words.
'
-    >>> markdown.markdown('__Strong__ still works.', \
-                          extensions=['smart_strong'])
-    u'
Strong still works.
'
-    >>> markdown.markdown('__this__works__too__.', \
-                          extensions=['smart_strong'])
-    u'
this__works__too.
'
-
-This extension is also included with the [Extra](extra.html) Extension. You may
-call that extension to get this behavior with all the other features of 'Extra'.
-
-    >>> markdown.markdown(text, extensions=['extra'])
-
diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.txt
new file mode 100644
index 0000000..8de574f
--- /dev/null
+++ b/docs/extensions/smart_strong.txt
@@ -0,0 +1,37 @@
+title:      Smart Strong Extension
+prev_title: Tables Extension
+prev_url:   tables.html
+next_title: CodeHilite Extension
+next_url:   code_hilite.html
+
+Smart_Strong
+============
+
+Summary
+-------
+
+The Markdown Smart_Strong Extension adds smarter handling of double underscores
+within words. This does for double underscores what 
+[smart_emphasis](../reference.html#smart_emphasis) does for single underscores.
+
+The Smart_Strong Extension is included in the standard Markdown library.
+
+Usage
+-----
+
+    >>> import markdown
+    >>> markdown.markdown('Text with double__underscore__words.', \
+                          extensions=['smart_strong'])
+    u'
Text with double__underscore__words.
'
+    >>> markdown.markdown('__Strong__ still works.', \
+                          extensions=['smart_strong'])
+    u'
Strong still works.
'
+    >>> markdown.markdown('__this__works__too__.', \
+                          extensions=['smart_strong'])
+    u'
this__works__too.
'
+
+This extension is also included with the [Extra](extra.html) Extension. You may
+call that extension to get this behavior with all the other features of 'Extra'.
+
+    >>> markdown.markdown(text, extensions=['extra'])
+
diff --git a/docs/extensions/tables.md b/docs/extensions/tables.md
deleted file mode 100644
index bb0872a..0000000
--- a/docs/extensions/tables.md
+++ /dev/null
@@ -1,58 +0,0 @@
-title:      Table Extension
-prev_title: Footnotes Extension
-prev_url:   footnotes.html
-next_title: Smart Strong Extension
-next_url:   smart_strong.html
-
-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:
-
-    
-      
-        
-          
-          
-        
-      
-      
-        
-          
-          
-        
-        
-          
-          
-        
-      
-    
First HeaderSecond Header
Content CellContent Cell
Content CellContent Cell

-
-Usage
------
-
-From the Python interpreter:
-
-    >>> html = markdown.markdown(text, ['tables'])
-
diff --git a/docs/extensions/tables.txt b/docs/extensions/tables.txt
new file mode 100644
index 0000000..bb0872a
--- /dev/null
+++ b/docs/extensions/tables.txt
@@ -0,0 +1,58 @@
+title:      Table Extension
+prev_title: Footnotes Extension
+prev_url:   footnotes.html
+next_title: Smart Strong Extension
+next_url:   smart_strong.html
+
+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:
+
+    
+      
+        
+          
+          
+        
+      
+      
+        
+          
+          
+        
+        
+          
+          
+        
+      
+    
First HeaderSecond Header
Content CellContent Cell
Content CellContent Cell

+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> html = markdown.markdown(text, ['tables'])
+
diff --git a/docs/extensions/toc.md b/docs/extensions/toc.md
deleted file mode 100644
index 632294b..0000000
--- a/docs/extensions/toc.md
+++ /dev/null
@@ -1,56 +0,0 @@
-title:      Table of Contents Extension
-prev_title: Sane Lists Extension
-prev_url:   sane_lists.html
-next_title: Wikilinks Extension
-next_url:   wikilinks.html
-
-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:
-
-    

-      
-    

-    
Header 1

-    
Header 2

-
-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 ``
``. Defaults to ``None``.
-* **anchorlink**: Set to ``True`` to have the headers link to themselves. 
-  Default is ``False``.
diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt
new file mode 100644
index 0000000..632294b
--- /dev/null
+++ b/docs/extensions/toc.txt
@@ -0,0 +1,56 @@
+title:      Table of Contents Extension
+prev_title: Sane Lists Extension
+prev_url:   sane_lists.html
+next_title: Wikilinks Extension
+next_url:   wikilinks.html
+
+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:
+
+    

+      
+    

+    
Header 1

+    
Header 2

+
+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 ``
``. Defaults to ``None``.
+* **anchorlink**: Set to ``True`` to have the headers link to themselves. 
+  Default is ``False``.
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:
-
-    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.

-
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.

+
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index 570f36b..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1,66 +0,0 @@
-next_url:   install.html
-next_title: Installation
-
-Python-Markdown
-===============
-
-This is a Python implementation of John Gruber's 
-[Markdown](http://daringfireball.net/projects/markdown/). 
-It is almost completely compliant with the reference implementation,
-though there are a few very minor differences. See John's 
-[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) 
-for the syntax rules.
-
-See the [installation instructions](install.html) to get started.
-
-Features
---------
-
-In addition to the basic markdown syntax, Python-Markdown supports the following
-features:
-
-* __International Input__
-
-    Python-Markdown will accept [input](reference.html#text) in any language 
-    supported by Unicode including bi-directional text. In fact the test suite 
-    includes documents written in Russian and Arabic.
-
-* __Middle-Word Emphasis__
-
-    Python-Markdown defaults to ignoring middle-word emphasis. In other words,
-    `some_long_filename.txt` will not become `somelongfilename.txt`.
-    This can be switched off if desired. See the 
-    [Library Reference](reference.html#smart_emphasis) for details.
-
-* __Extensions__
-
-    Various [extensions](extensions/index.html) are provided (including 
-    [extra](extensions/extra.html)) to expand the base syntax. Additionally, 
-    a public [Extension API](extensions/api.html) is available to write 
-    your own extensions.
-
-* __Output Formats__
-
-    Python-Markdown can output documents in HTML4, XHTML and HTML5. See the
-    [Library Reference](reference.html#output_format) for details.
-
-* __"Safe Mode"__
-
-    When using Python-Markdown to parse input from untrusted users on the web,
-    the handling of raw HTML can be controlled in various ways to prevent 
-    harmful code from being injected into your site. See the
-    [Library Reference](reference.html#safe_mode) for details.
-
-* __Command Line Interface__
-
-    In addition to being a Python Library, a 
-    [command line script](cli.html) is available for your convenience.
-
-Support
--------
-
-You may ask for help and discuss various other issues on the [mailing list][] 
-and report bugs on the [bug tracker][].
-
-[mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss
-[bug tracker]: http://github.com/waylan/Python-Markdown/issues 
diff --git a/docs/index.txt b/docs/index.txt
new file mode 100644
index 0000000..570f36b
--- /dev/null
+++ b/docs/index.txt
@@ -0,0 +1,66 @@
+next_url:   install.html
+next_title: Installation
+
+Python-Markdown
+===============
+
+This is a Python implementation of John Gruber's 
+[Markdown](http://daringfireball.net/projects/markdown/). 
+It is almost completely compliant with the reference implementation,
+though there are a few very minor differences. See John's 
+[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) 
+for the syntax rules.
+
+See the [installation instructions](install.html) to get started.
+
+Features
+--------
+
+In addition to the basic markdown syntax, Python-Markdown supports the following
+features:
+
+* __International Input__
+
+    Python-Markdown will accept [input](reference.html#text) in any language 
+    supported by Unicode including bi-directional text. In fact the test suite 
+    includes documents written in Russian and Arabic.
+
+* __Middle-Word Emphasis__
+
+    Python-Markdown defaults to ignoring middle-word emphasis. In other words,
+    `some_long_filename.txt` will not become `somelongfilename.txt`.
+    This can be switched off if desired. See the 
+    [Library Reference](reference.html#smart_emphasis) for details.
+
+* __Extensions__
+
+    Various [extensions](extensions/index.html) are provided (including 
+    [extra](extensions/extra.html)) to expand the base syntax. Additionally, 
+    a public [Extension API](extensions/api.html) is available to write 
+    your own extensions.
+
+* __Output Formats__
+
+    Python-Markdown can output documents in HTML4, XHTML and HTML5. See the
+    [Library Reference](reference.html#output_format) for details.
+
+* __"Safe Mode"__
+
+    When using Python-Markdown to parse input from untrusted users on the web,
+    the handling of raw HTML can be controlled in various ways to prevent 
+    harmful code from being injected into your site. See the
+    [Library Reference](reference.html#safe_mode) for details.
+
+* __Command Line Interface__
+
+    In addition to being a Python Library, a 
+    [command line script](cli.html) is available for your convenience.
+
+Support
+-------
+
+You may ask for help and discuss various other issues on the [mailing list][] 
+and report bugs on the [bug tracker][].
+
+[mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss
+[bug tracker]: http://github.com/waylan/Python-Markdown/issues 
diff --git a/docs/install.md b/docs/install.md
deleted file mode 100644
index cb20a73..0000000
--- a/docs/install.md
+++ /dev/null
@@ -1,83 +0,0 @@
-title:      Installation
-prev_title: Summary
-prev_url:   index.html
-next_title: Library Reference
-next_url:   reference.html
-
-Installing Python-Markdown
-==========================
-
-The Easy Way
-------------
-
-The easiest way to install Python-Markdown is simply to type one of the 
-following commands from the command line as an Admin/Root user:
-
-    pip install markdown
-
-or
-
-    easy_install markdown
-
-That's it! Your ready to [use](reference.html) Python-Markdown. Enjoy!
-
-Installing on Windows
----------------------
-
-Download the Windows installer (.exe) from 
-[PyPI](http://pypi.python.org/pypi/Markdown)
-
-Double-click the file and follow the instructions.
-
-If you prefer to manually install Python-Markdown in Windows, download the
-Zip file, unzip it, and on the command line in the directory you unzipped to,
-run the following command:
-
-    C://path/to/python.exe setup.py install
-
-If you plan to use the provided command line script, you need to make sure your
-script directory is on your system path. On a typical Python install of Windows
-the Scripts directory is `C:\PythonXX\Scripts\` (were "XX" is the Python version
-number, i.e., "27"). Adjust the path according to your system and add to your 
-system path.
-
-Installing on *nix Systems
---------------------------
-
-From the command line do the following (where 2.x is the version number):
-
-    wget http://pypi.python.org/packages/source/M/Markdown/Markdown-2.x.tar.gz
-    tar xvzf Markdown-2.x.tar.gz
-    cd markdown-2.x/
-    sudo python setup.py install
-
-See [PyPI](http://pypi.python.org/pypi/Markdown) for all available versions.
-
-Using the Git Repository
-------------------------
-
-If you're the type that likes to live on the edge, you may want to keep up with 
-the latest additions and bug fixes in the repository between releases.
-Python-Markdown is maintained in a Git repository on github.com. To
-get a copy of Python-Markdown from the repository do the following from the
-command line:
-
-    git clone git://github.com/waylan/Python-Markdown.git python-markdown
-    cd python-markdown
-    python setup.py install
-
-Dependencies
-------------
-
-Python-Markdown requires the ElementTree module to be installed. In Python 2.5+ 
-ElementTree is included as part of the standard library at 
-`xml.etree.ElementTree` and/or `xml.etree.cElementTree`. For earlier versions 
-of Python, the library needs to be installed.  However, Python-Markdown's 
-install script will automaticaly detect the missing library and download and 
-install the "ElementTree" library for you if your system has internet access. 
-If you would like to use the "cElementTree" library (which is faster), you can 
-install it manually. Markdown will check for the faster "c" library first and 
-fall back to the slower python implementation when it is not available.
-
-See  for more information or to 
-download the latest version of ElementTree.
diff --git a/docs/install.txt b/docs/install.txt
new file mode 100644
index 0000000..cb20a73
--- /dev/null
+++ b/docs/install.txt
@@ -0,0 +1,83 @@
+title:      Installation
+prev_title: Summary
+prev_url:   index.html
+next_title: Library Reference
+next_url:   reference.html
+
+Installing Python-Markdown
+==========================
+
+The Easy Way
+------------
+
+The easiest way to install Python-Markdown is simply to type one of the 
+following commands from the command line as an Admin/Root user:
+
+    pip install markdown
+
+or
+
+    easy_install markdown
+
+That's it! Your ready to [use](reference.html) Python-Markdown. Enjoy!
+
+Installing on Windows
+---------------------
+
+Download the Windows installer (.exe) from 
+[PyPI](http://pypi.python.org/pypi/Markdown)
+
+Double-click the file and follow the instructions.
+
+If you prefer to manually install Python-Markdown in Windows, download the
+Zip file, unzip it, and on the command line in the directory you unzipped to,
+run the following command:
+
+    C://path/to/python.exe setup.py install
+
+If you plan to use the provided command line script, you need to make sure your
+script directory is on your system path. On a typical Python install of Windows
+the Scripts directory is `C:\PythonXX\Scripts\` (were "XX" is the Python version
+number, i.e., "27"). Adjust the path according to your system and add to your 
+system path.
+
+Installing on *nix Systems
+--------------------------
+
+From the command line do the following (where 2.x is the version number):
+
+    wget http://pypi.python.org/packages/source/M/Markdown/Markdown-2.x.tar.gz
+    tar xvzf Markdown-2.x.tar.gz
+    cd markdown-2.x/
+    sudo python setup.py install
+
+See [PyPI](http://pypi.python.org/pypi/Markdown) for all available versions.
+
+Using the Git Repository
+------------------------
+
+If you're the type that likes to live on the edge, you may want to keep up with 
+the latest additions and bug fixes in the repository between releases.
+Python-Markdown is maintained in a Git repository on github.com. To
+get a copy of Python-Markdown from the repository do the following from the
+command line:
+
+    git clone git://github.com/waylan/Python-Markdown.git python-markdown
+    cd python-markdown
+    python setup.py install
+
+Dependencies
+------------
+
+Python-Markdown requires the ElementTree module to be installed. In Python 2.5+ 
+ElementTree is included as part of the standard library at 
+`xml.etree.ElementTree` and/or `xml.etree.cElementTree`. For earlier versions 
+of Python, the library needs to be installed.  However, Python-Markdown's 
+install script will automaticaly detect the missing library and download and 
+install the "ElementTree" library for you if your system has internet access. 
+If you would like to use the "cElementTree" library (which is faster), you can 
+install it manually. Markdown will check for the faster "c" library first and 
+fall back to the slower python implementation when it is not available.
+
+See  for more information or to 
+download the latest version of ElementTree.
diff --git a/docs/reference.md b/docs/reference.md
deleted file mode 100644
index c1561f7..0000000
--- a/docs/reference.md
+++ /dev/null
@@ -1,244 +0,0 @@
-title:      Library Reference
-prev_title: Installation
-prev_url:   install.html
-next_title: Command Line
-next_url:   cli.html
-
-
-Using Markdown as a Python Library
-==================================
-
-First and foremost, Python-Markdown is intended to be a python library module
-used by various projects to convert Markdown syntax into HTML.
-
-The Basics
-----------
-
-To use markdown as a module:
-
-    import markdown
-    html = markdown.markdown(your_text_string)
-
-The Details
------------
-
-Python-Markdown provides two public functions ([`markdown.markdown`](#markdown)
-and [`markdown.markdownFromFile`](#markdownFromFile)) both of which wrap the 
-public class [`markdown.Markdown`](#Markdown). If you're processing one 
-document at a time, the functions will serve your needs. However, if you need 
-to process multiple documents, it may be advantageous to create a single 
-instance of the `markdown.Markdown` class and pass multiple documents through 
-it.
-
-### `markdown.markdown (text [, **kwargs])` {: #markdown }
-
-The following options are available on the `markdown.markdown` function:
-
-* __`text`__{: #text } (required): The source text string.
-
-    Note that Python-Markdown expects **Unicode** as input (although
-    a simple ASCII string may work) and returns output as Unicode.
-    Do not pass encoded strings to it! If your input is encoded, (e.g. as 
-    UTF-8), it is your responsibility to decode it.  For example:
-
-        input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
-        text = input_file.read()
-        html = markdown.markdown(text)
-
-    If you want to write the output to disk, you must encode it yourself:
-
-        output_file = codecs.open("some_file.html", "w", 
-                                  encoding="utf-8", 
-                                  errors="xmlcharrefreplace"
-        )
-        output_file.write(html)
-
-* __`extensions`__{: #extensions }: A list of extensions.
-
-    Python-Markdown provides an API for third parties to write extensions to
-    the parser adding their own additions or changes to the syntax. A few
-    commonly used extensions are shipped with the markdown library. See
-    the [extension documentation](extensions/index.html) for a list of 
-    available extensions.
-
-    The list of extensions may contain instances of extensions or stings of
-    extension names. If an extension name is provided as a string, the
-    extension must be importable as a python module either within the 
-    `markdown.extensions` package or on your PYTHONPATH with a name starting 
-    with `mdx_`, followed by the name of the extension.  Thus, 
-    `extensions=['extra']` will first look for the module 
-    `markdown.extensions.extra`, then a module named `mdx_extra`. 
-
-* __`extension-configs`__{: #extension_configs }: A dictionary of 
-  configuration settings for extensions.
-
-    The dictionary must be of the following format:
-
-        extension-configs = {'extension_name_1': 
-                               [
-                                  ('option_1', 'value_1'),
-                                  ('option_2', 'value_2')
-                               ],
-                             'extension_name_2':
-                               [
-                                  ('option_1', 'value_1')
-                               ]
-                            }
-    See the documentation specific to the extension you are using for help in 
-    specifying configuration settings for that extension.
-
-* __`output_format`__{: #output_format }: Format of output. 
-
-    Supported formats are:
-
-    * `"xhtml1"`: Outputs XHTML 1.x. **Default**.
-    * `"xhtml5"`: Outputs XHTML style tags of HTML 5
-    * `"xhtml"`: Outputs latest supported version of XHTML (currently XHTML 1.1).
-    * `"html4"`: Outputs HTML 4
-    * `"html5"`: Outputs HTML style tags of HTML 5
-    * `"html"`: Outputs latest supported version of HTML (currently HTML 4).
-
-    Note that it is suggested that the more specific formats ("xhtml1",
-    "html5", & "html4") be used as "xhtml" or "html" may change in the future
-    if it makes sense at that time. The values can either be lowercase or 
-    uppercase.
-
-* __`safe_mode`__{: #safe_mode }: Disallow raw html.
-
-    If you are using Markdown on a web system which will transform text 
-    provided by untrusted users, you may want to use the "safe_mode" 
-    option which ensures that the user's HTML tags are either replaced, 
-    removed or escaped. (They can still create links using Markdown syntax.)
-
-    The following values are accepted:
-
-    * `False` (Default): Raw HTML is passed through unaltered.
-
-    * `replace`: Replace all HTML blocks with the text assigned to 
-      `html_replacement_text` To maintain backward compatibility, setting 
-      `safe_mode=True` will have the same effect as `safe_mode='replace'`.   
-
-        To replace raw HTML with something other than the default, do:
-
-            md = markdown.Markdown(safe_mode='replace', 
-                               html_replacement_text='--RAW HTML NOT ALLOWED--')
-
-    * `remove`: All raw HTML will be completely stripped from the text with
-      no warning to the author.
-
-    * `escape`: All raw HTML will be escaped and included in the document.
-
-        For example, the following source:
-
-            Foo bar.
-
-        Will result in the following HTML:
-
-            
Foo <b>bar</b>.

-
-    Note that "safe_mode" does not alter the `enable_attributes` option, which 
-    could allow someone to inject javascript (i.e., `{@onclick=alert(1)}`). You 
-    may also want to set `enable_attributes=False` when using "safe_mode".
-
-* __`html_replacement_text`__{: #html_replacement_text }: Text used when 
-  safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`.
-
-* __`tab_length`__{: #tab_length }: Length of tabs in the source. Default: 4
-
-* __`enable_attributes`__{: #enable_attributes}: Enable the conversion of 
-  attributes. Default: True
-
-* __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_` 
-  intelligently Default: True
-
-* __`lazy_ol`__{: #lazy_ol }: Ignore number of first item of ordered lists. 
-  Default: True
-
-    Given the following list:
-
-        4. Apples
-        5. Oranges
-        6. Pears
-
-    By default markdown will ignore the fact the the first line started 
-    with item number "4" and the HTML list will start with a number "1".
-    If `lazy_ol` is set to `True`, then markdown will output the following
-    HTML:
-
-        
    
-          
  1. Apples
    2. 
-          
  2. Oranges
    3. 
-          
  3. Pears
    4. 
-        

-
-
-### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile }
-
-With a few exceptions, `markdown.markdownFromFile` accepts the same options as 
-`markdown.markdown`. It does **not** accept a `text` (or Unicode) string. 
-Instead, it accepts the following required options:
-
-* __`input`__{: #input } (required): The source text file.
-
-    `input` may be set to one of three options:
-
-    * a string which contains a path to a readable file on the file system,
-    * a readable file-like object,
-    * or `None` (default) which will read from `stdin`.
-
-* __`output`__{: #output }: The target which output is written to.
-
-    `output` may be set to one of three options:
-
-    * a string which contains a path to a writable file on the file system,
-    * a writable file-like object,
-    * or `None` (default) which will write to `stdout`.
-
-* __`encoding`__{: #encoding }: The encoding of the source text file. Defaults 
-  to "utf-8". The same encoding will always be used for input and output. 
-  The 'xmlcharrefreplace' error handler is used when encoding the output.
-
-    **Note:** This is the only place that decoding and encoding of unicode
-    takes place in Python-Markdown. If this rather naive solution does not
-    meet your specific needs, it is suggested that you write your own code
-    to handle your encoding/decoding needs.
-
-### `markdown.Markdown ([**kwargs])` {: #Markdown }
-
-The same options are available when initializing the `markdown.Markdown` class
-as on the [`markdown.markdown`](#markdown) function, except that the class does
-**not** accept a source text string on initialization. Rather, the source text
-string must be passed to one of two instance methods:
-
-* `Markdown.convert(source)` {: #convert }
-
-    The `source` text must meet the same requirements as the [`text`](#text) 
-    argument of the [`markdown.markdown`](#markdown) function.
-
-    You should also use this method if you want to process multiple strings
-    without creating a new instance of the class for each string.
-
-        md = markdown.Markdown()
-        html1 = md.convert(text1)
-        html2 = md.convert(text2)
-
-    Note that depending on which options and/or extensions are being used,
-    the parser may need its state reset between each call to `convert`.
-
-        html1 = md.convert(text1)
-        md.reset()
-        html2 = md.convert(text2)
-    
-    You can also change calls to `reset` togeather:
-    
-        html3 = md.reset().convert(text3)
-
-* `Markdown.convertFile(**kwargs)` {: #convertFile }
-
-    The arguments of this method are identical to the arguments of the same
-    name on the `markdown.markdownFromFile` function ([`input`](#input), 
-    [`output`](#output), and [`encoding`](#encoding)). As with the 
-    [`convert`](#convert) method, this method should be used to 
-    process multiple files without creating a new instance of the class for 
-    each document. State may need to be `reset` between each call to 
-    `convertFile` as is the case with `convert`.
diff --git a/docs/reference.txt b/docs/reference.txt
new file mode 100644
index 0000000..c1561f7
--- /dev/null
+++ b/docs/reference.txt
@@ -0,0 +1,244 @@
+title:      Library Reference
+prev_title: Installation
+prev_url:   install.html
+next_title: Command Line
+next_url:   cli.html
+
+
+Using Markdown as a Python Library
+==================================
+
+First and foremost, Python-Markdown is intended to be a python library module
+used by various projects to convert Markdown syntax into HTML.
+
+The Basics
+----------
+
+To use markdown as a module:
+
+    import markdown
+    html = markdown.markdown(your_text_string)
+
+The Details
+-----------
+
+Python-Markdown provides two public functions ([`markdown.markdown`](#markdown)
+and [`markdown.markdownFromFile`](#markdownFromFile)) both of which wrap the 
+public class [`markdown.Markdown`](#Markdown). If you're processing one 
+document at a time, the functions will serve your needs. However, if you need 
+to process multiple documents, it may be advantageous to create a single 
+instance of the `markdown.Markdown` class and pass multiple documents through 
+it.
+
+### `markdown.markdown (text [, **kwargs])` {: #markdown }
+
+The following options are available on the `markdown.markdown` function:
+
+* __`text`__{: #text } (required): The source text string.
+
+    Note that Python-Markdown expects **Unicode** as input (although
+    a simple ASCII string may work) and returns output as Unicode.
+    Do not pass encoded strings to it! If your input is encoded, (e.g. as 
+    UTF-8), it is your responsibility to decode it.  For example:
+
+        input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
+        text = input_file.read()
+        html = markdown.markdown(text)
+
+    If you want to write the output to disk, you must encode it yourself:
+
+        output_file = codecs.open("some_file.html", "w", 
+                                  encoding="utf-8", 
+                                  errors="xmlcharrefreplace"
+        )
+        output_file.write(html)
+
+* __`extensions`__{: #extensions }: A list of extensions.
+
+    Python-Markdown provides an API for third parties to write extensions to
+    the parser adding their own additions or changes to the syntax. A few
+    commonly used extensions are shipped with the markdown library. See
+    the [extension documentation](extensions/index.html) for a list of 
+    available extensions.
+
+    The list of extensions may contain instances of extensions or stings of
+    extension names. If an extension name is provided as a string, the
+    extension must be importable as a python module either within the 
+    `markdown.extensions` package or on your PYTHONPATH with a name starting 
+    with `mdx_`, followed by the name of the extension.  Thus, 
+    `extensions=['extra']` will first look for the module 
+    `markdown.extensions.extra`, then a module named `mdx_extra`. 
+
+* __`extension-configs`__{: #extension_configs }: A dictionary of 
+  configuration settings for extensions.
+
+    The dictionary must be of the following format:
+
+        extension-configs = {'extension_name_1': 
+                               [
+                                  ('option_1', 'value_1'),
+                                  ('option_2', 'value_2')
+                               ],
+                             'extension_name_2':
+                               [
+                                  ('option_1', 'value_1')
+                               ]
+                            }
+    See the documentation specific to the extension you are using for help in 
+    specifying configuration settings for that extension.
+
+* __`output_format`__{: #output_format }: Format of output. 
+
+    Supported formats are:
+
+    * `"xhtml1"`: Outputs XHTML 1.x. **Default**.
+    * `"xhtml5"`: Outputs XHTML style tags of HTML 5
+    * `"xhtml"`: Outputs latest supported version of XHTML (currently XHTML 1.1).
+    * `"html4"`: Outputs HTML 4
+    * `"html5"`: Outputs HTML style tags of HTML 5
+    * `"html"`: Outputs latest supported version of HTML (currently HTML 4).
+
+    Note that it is suggested that the more specific formats ("xhtml1",
+    "html5", & "html4") be used as "xhtml" or "html" may change in the future
+    if it makes sense at that time. The values can either be lowercase or 
+    uppercase.
+
+* __`safe_mode`__{: #safe_mode }: Disallow raw html.
+
+    If you are using Markdown on a web system which will transform text 
+    provided by untrusted users, you may want to use the "safe_mode" 
+    option which ensures that the user's HTML tags are either replaced, 
+    removed or escaped. (They can still create links using Markdown syntax.)
+
+    The following values are accepted:
+
+    * `False` (Default): Raw HTML is passed through unaltered.
+
+    * `replace`: Replace all HTML blocks with the text assigned to 
+      `html_replacement_text` To maintain backward compatibility, setting 
+      `safe_mode=True` will have the same effect as `safe_mode='replace'`.   
+
+        To replace raw HTML with something other than the default, do:
+
+            md = markdown.Markdown(safe_mode='replace', 
+                               html_replacement_text='--RAW HTML NOT ALLOWED--')
+
+    * `remove`: All raw HTML will be completely stripped from the text with
+      no warning to the author.
+
+    * `escape`: All raw HTML will be escaped and included in the document.
+
+        For example, the following source:
+
+            Foo bar.
+
+        Will result in the following HTML:
+
+            
Foo <b>bar</b>.

+
+    Note that "safe_mode" does not alter the `enable_attributes` option, which 
+    could allow someone to inject javascript (i.e., `{@onclick=alert(1)}`). You 
+    may also want to set `enable_attributes=False` when using "safe_mode".
+
+* __`html_replacement_text`__{: #html_replacement_text }: Text used when 
+  safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`.
+
+* __`tab_length`__{: #tab_length }: Length of tabs in the source. Default: 4
+
+* __`enable_attributes`__{: #enable_attributes}: Enable the conversion of 
+  attributes. Default: True
+
+* __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_` 
+  intelligently Default: True
+
+* __`lazy_ol`__{: #lazy_ol }: Ignore number of first item of ordered lists. 
+  Default: True
+
+    Given the following list:
+
+        4. Apples
+        5. Oranges
+        6. Pears
+
+    By default markdown will ignore the fact the the first line started 
+    with item number "4" and the HTML list will start with a number "1".
+    If `lazy_ol` is set to `True`, then markdown will output the following
+    HTML:
+
+        
    
+          
  1. Apples
    2. 
+          
  2. Oranges
    3. 
+          
  3. Pears
    4. 
+        

+
+
+### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile }
+
+With a few exceptions, `markdown.markdownFromFile` accepts the same options as 
+`markdown.markdown`. It does **not** accept a `text` (or Unicode) string. 
+Instead, it accepts the following required options:
+
+* __`input`__{: #input } (required): The source text file.
+
+    `input` may be set to one of three options:
+
+    * a string which contains a path to a readable file on the file system,
+    * a readable file-like object,
+    * or `None` (default) which will read from `stdin`.
+
+* __`output`__{: #output }: The target which output is written to.
+
+    `output` may be set to one of three options:
+
+    * a string which contains a path to a writable file on the file system,
+    * a writable file-like object,
+    * or `None` (default) which will write to `stdout`.
+
+* __`encoding`__{: #encoding }: The encoding of the source text file. Defaults 
+  to "utf-8". The same encoding will always be used for input and output. 
+  The 'xmlcharrefreplace' error handler is used when encoding the output.
+
+    **Note:** This is the only place that decoding and encoding of unicode
+    takes place in Python-Markdown. If this rather naive solution does not
+    meet your specific needs, it is suggested that you write your own code
+    to handle your encoding/decoding needs.
+
+### `markdown.Markdown ([**kwargs])` {: #Markdown }
+
+The same options are available when initializing the `markdown.Markdown` class
+as on the [`markdown.markdown`](#markdown) function, except that the class does
+**not** accept a source text string on initialization. Rather, the source text
+string must be passed to one of two instance methods:
+
+* `Markdown.convert(source)` {: #convert }
+
+    The `source` text must meet the same requirements as the [`text`](#text) 
+    argument of the [`markdown.markdown`](#markdown) function.
+
+    You should also use this method if you want to process multiple strings
+    without creating a new instance of the class for each string.
+
+        md = markdown.Markdown()
+        html1 = md.convert(text1)
+        html2 = md.convert(text2)
+
+    Note that depending on which options and/or extensions are being used,
+    the parser may need its state reset between each call to `convert`.
+
+        html1 = md.convert(text1)
+        md.reset()
+        html2 = md.convert(text2)
+    
+    You can also change calls to `reset` togeather:
+    
+        html3 = md.reset().convert(text3)
+
+* `Markdown.convertFile(**kwargs)` {: #convertFile }
+
+    The arguments of this method are identical to the arguments of the same
+    name on the `markdown.markdownFromFile` function ([`input`](#input), 
+    [`output`](#output), and [`encoding`](#encoding)). As with the 
+    [`convert`](#convert) method, this method should be used to 
+    process multiple files without creating a new instance of the class for 
+    each document. State may need to be `reset` between each call to 
+    `convertFile` as is the case with `convert`.
diff --git a/docs/release-2.0.1.md b/docs/release-2.0.1.md
deleted file mode 100644
index e5946b2..0000000
--- a/docs/release-2.0.1.md
+++ /dev/null
@@ -1,16 +0,0 @@
-Python-Markdown 2.0.1 Release Notes
-===================================
-
-Python-Markdown 2.0.1 is a bug-fix release. No new features have been added.
-Most notably, various issues with the command line script have been fixed.
-There have also been a few fixes for minor parsing bugs in some edge cases.
-For a full list of changes, see the git log.
-
-Backwards-incompatible Changes
-------------------------------
-
-Due to various complications in how Python handles command line scripts in 
-differance systems and with differant installation tools, we were forced to 
-rename the commandline script to ``markdown`` (no ".py"). A matching batch
-script will get installed on Windows. Any shell scripts which call 
-``markdown.py`` will need to be altered to call ``markdown`` instead.
diff --git a/docs/release-2.0.1.txt b/docs/release-2.0.1.txt
new file mode 100644
index 0000000..e5946b2
--- /dev/null
+++ b/docs/release-2.0.1.txt
@@ -0,0 +1,16 @@
+Python-Markdown 2.0.1 Release Notes
+===================================
+
+Python-Markdown 2.0.1 is a bug-fix release. No new features have been added.
+Most notably, various issues with the command line script have been fixed.
+There have also been a few fixes for minor parsing bugs in some edge cases.
+For a full list of changes, see the git log.
+
+Backwards-incompatible Changes
+------------------------------
+
+Due to various complications in how Python handles command line scripts in 
+differance systems and with differant installation tools, we were forced to 
+rename the commandline script to ``markdown`` (no ".py"). A matching batch
+script will get installed on Windows. Any shell scripts which call 
+``markdown.py`` will need to be altered to call ``markdown`` instead.
diff --git a/docs/release-2.0.2.md b/docs/release-2.0.2.md
deleted file mode 100644
index 8ae9a3d..0000000
--- a/docs/release-2.0.2.md
+++ /dev/null
@@ -1,9 +0,0 @@
-Python-Markdown 2.0.2 Release Notes
-===================================
-
-Python-Markdown 2.0.2 is a bug-fix release. No new features have been added.
-Most notably, the setup script has been updated to include a dependency on 
-ElementTree on older versions of Python (< 2.5). There have also been a few 
-fixes for minor parsing bugs in some edge cases. For a full list of changes, 
-see the git log.
-
diff --git a/docs/release-2.0.2.txt b/docs/release-2.0.2.txt
new file mode 100644
index 0000000..8ae9a3d
--- /dev/null
+++ b/docs/release-2.0.2.txt
@@ -0,0 +1,9 @@
+Python-Markdown 2.0.2 Release Notes
+===================================
+
+Python-Markdown 2.0.2 is a bug-fix release. No new features have been added.
+Most notably, the setup script has been updated to include a dependency on 
+ElementTree on older versions of Python (< 2.5). There have also been a few 
+fixes for minor parsing bugs in some edge cases. For a full list of changes, 
+see the git log.
+
diff --git a/docs/release-2.0.md b/docs/release-2.0.md
deleted file mode 100644
index b1f71ad..0000000
--- a/docs/release-2.0.md
+++ /dev/null
@@ -1,67 +0,0 @@
-Python-Markdown 2.0 Release Notes
-=================================
-
-We are happy to release Python-Markdown 2.0, which has been over a year in the 
-making. We have rewritten significant portions of the code, dramatically 
-extending the extension API, increased performance, and added numerous 
-extensions to the distribution (including an extension that mimics PHP Markdown
-Extra), all while maintaining backward compatibility with the end user API in
-version 1.7.
-
-Python-Markdown supports Python versions 2.3, 2.4, 2.5, and 2.6. We've even 
-released a version converted to Python 3.0!
-
-Backwards-incompatible Changes
-------------------------------
-
-While Python-Markdown has experienced numerous internal changes, those changes 
-should only affect extension authors. If you have not written your own 
-extensions, then you should not need to make any changes to your code. 
-However, you may want to ensure that any third party extensions you are using
-are compatible with the new API.
-
-The new extension API is fully documented in [[writing_extensions]]. Below is a
-summary of the significant changes:
-
-* The old home-grown NanoDOM has been replaced with ElementTree. Therefore all
-  extensions must use ElementTree rather than the old NanoDOM.
-* The various processors and patterns are now stored with OrderedDicts rather 
-  than lists. Any code adding processors and/or patterns into Python-Markdown 
-  will need to be adjusted to use the new API using OrderedDicts.
-* The various types of processors available have been either combined, added, 
-  or removed. Ensure that your processors match the currently supported types.
-
-What's New in Python-Markdown 2.0
----------------------------------
-
-Thanks to the work of Artem Yunusov as part of GSoC 2008, Python-Markdown uses
-ElementTree internally to build the (X)HTML document from markdown source text.
-This has resolved various issues with the older home-grown NanoDOM and made
-notable increases in performance.
-
-Artem also refactored the Inline Patterns to better support nested patterns 
-which has resolved many inconsistencies in Python-Markdown's parsing of the 
-markdown syntax.
-
-The core parser had been completely rewritten, increasing performance and, for 
-the first time, making it possible to override/add/change the way block level
-content is parsed.
-
-Python-Markdown now parses markdown source text more closely to the other 
-popular implementations (Perl, PHP, etc.) than it ever has before. With the
-exception of a few minor insignificant differences, any difference should be
-considered a bug, rather than a limitation of the parser.
-
-The option to return HTML4 output as apposed to XHTML has been added. In 
-addition, extensions should be able to easily add additional output formats.
-
-As part of implementing markdown in the Dr. Project project (a Trac fork), among
-other things, David Wolever refactored the "extension" keyword so that it
-accepts either the extension names as strings or instances of extensions. This
-makes it possible to include multiple extensions in a single module.
-
-Numerous extensions are included in the distribution by default. See
-[[available_extensions]] for a complete list.
-
-See the [[change_log]] for a full list of changes.
-
diff --git a/docs/release-2.0.txt b/docs/release-2.0.txt
new file mode 100644
index 0000000..b1f71ad
--- /dev/null
+++ b/docs/release-2.0.txt
@@ -0,0 +1,67 @@
+Python-Markdown 2.0 Release Notes
+=================================
+
+We are happy to release Python-Markdown 2.0, which has been over a year in the 
+making. We have rewritten significant portions of the code, dramatically 
+extending the extension API, increased performance, and added numerous 
+extensions to the distribution (including an extension that mimics PHP Markdown
+Extra), all while maintaining backward compatibility with the end user API in
+version 1.7.
+
+Python-Markdown supports Python versions 2.3, 2.4, 2.5, and 2.6. We've even 
+released a version converted to Python 3.0!
+
+Backwards-incompatible Changes
+------------------------------
+
+While Python-Markdown has experienced numerous internal changes, those changes 
+should only affect extension authors. If you have not written your own 
+extensions, then you should not need to make any changes to your code. 
+However, you may want to ensure that any third party extensions you are using
+are compatible with the new API.
+
+The new extension API is fully documented in [[writing_extensions]]. Below is a
+summary of the significant changes:
+
+* The old home-grown NanoDOM has been replaced with ElementTree. Therefore all
+  extensions must use ElementTree rather than the old NanoDOM.
+* The various processors and patterns are now stored with OrderedDicts rather 
+  than lists. Any code adding processors and/or patterns into Python-Markdown 
+  will need to be adjusted to use the new API using OrderedDicts.
+* The various types of processors available have been either combined, added, 
+  or removed. Ensure that your processors match the currently supported types.
+
+What's New in Python-Markdown 2.0
+---------------------------------
+
+Thanks to the work of Artem Yunusov as part of GSoC 2008, Python-Markdown uses
+ElementTree internally to build the (X)HTML document from markdown source text.
+This has resolved various issues with the older home-grown NanoDOM and made
+notable increases in performance.
+
+Artem also refactored the Inline Patterns to better support nested patterns 
+which has resolved many inconsistencies in Python-Markdown's parsing of the 
+markdown syntax.
+
+The core parser had been completely rewritten, increasing performance and, for 
+the first time, making it possible to override/add/change the way block level
+content is parsed.
+
+Python-Markdown now parses markdown source text more closely to the other 
+popular implementations (Perl, PHP, etc.) than it ever has before. With the
+exception of a few minor insignificant differences, any difference should be
+considered a bug, rather than a limitation of the parser.
+
+The option to return HTML4 output as apposed to XHTML has been added. In 
+addition, extensions should be able to easily add additional output formats.
+
+As part of implementing markdown in the Dr. Project project (a Trac fork), among
+other things, David Wolever refactored the "extension" keyword so that it
+accepts either the extension names as strings or instances of extensions. This
+makes it possible to include multiple extensions in a single module.
+
+Numerous extensions are included in the distribution by default. See
+[[available_extensions]] for a complete list.
+
+See the [[change_log]] for a full list of changes.
+
diff --git a/docs/release-2.1.0.md b/docs/release-2.1.0.md
deleted file mode 100644
index f6c203b..0000000
--- a/docs/release-2.1.0.md
+++ /dev/null
@@ -1,117 +0,0 @@
-Python-Markdown 2.1.0 Release Notes
-===================================
-
-We are pleased to release Python-Markdown 2.1 which makes many 
-improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. 
-While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline 
-with other implementations, some internal improvements were made to the parser, 
-a few new builtin extensions were added, and HTML5 support was added.
-
-Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out 
-of the box. In fact, the same codebase installs on Python 3.1 and 3.2 with no 
-extra work by the end user.
-
-Backwards-incompatible Changes
-------------------------------
-
-While Python-Markdown has received only minor internal changes since the last
-release, there are a few backward-incompatible changes to note:
-
-* Support had been dropped for Python 2.3. No guarantees are made that the 
-library will work in any version of Python lower than 2.4. Additionally, while 
-the library had been tested with Python 2.4, consider Python 2.4 support to be 
-depreciated. It is not likely that any future versions will continue to support
-any version of Python less than 2.5. Note that Python 3.0 is not supported due 
-to a bug in its 2to3 tool. If you must use Python-Markdown with Python 3.0, it 
-is suggested you manually use Python 3.1's 2to3 tool to do a conversion.
-
-* Python-Markdown previously accepted positional arguments on its class and
-wrapper methods. It now expects keyword arguments. Currently, the positional
-arguments should continue to work, but the solution feels hacky and may be 
-removed in a future version. All users are encouraged to use keyword arguments 
-as documented in [Using Markdown as a Python Library](using_as_module.html).
-
-* Past versions of Python-Markdown provided module level Global variables which
-controlled the behavior of a few different aspects of the parser. Those global
-variables have been replaced with attributes on the Markdown class. 
-Additionally, those attributes are settable as keyword arguments when 
-initializing a class instance. Therefore, if you were editing the global 
-variables (either by editing the source or by overriding them in your code), 
-you should now set them on the class. See 
-[Using Markdown as a Python Library](using_as_module.html) for the options 
-available.
-
-* If you have been using the [HeaderID](extensions/header_id.html) extension 
-to define custom ids on headers, you will want to switch to using the new 
-[Attribute List](extensions/attr_list.html) extension. The HeaderId extension 
-now only auto-generates ids on headers which have not already had ids defined. 
-Note that the [Extra](extensions/extra.html) extension has been switched to use 
-Attribute Lists instead of HeaderId as it did previously.
-
-* Some code was moved into the `markdown.util` namespace which was previously
-in the `markdown` namespace. Extension authors may need to adjust a few
-import statements in their extensions to work with the changes.
-
-* The commandline script name was changed to `markdown_py`. The previous name
-(`markdown`) was conflicting with people (and Linux package systems) who also
-had markdown.pl installed on there system as markdown.pl's commandline script
-was also named `markdown`. Be aware that installing Python-Markdown 2.1
-will not remove the old versions of the script with different names. You
-may want to remove them yourself as they are unlikely to work properly.
-
-What's New in Python-Markdown 2.1
----------------------------------
-
-Three new extensions were added. [Attribute Lists](extensions/attr_list.html), 
-which was inspired by Maruku's feature of the same name, 
-[Newline to Break](extensions/nl2br.html), which was inspired by Github 
-Flavored Markdown, and [Smart Strong](extensions/smart_strong.html), which 
-fills a hole in the Extra extension.
-
-HTML5 is now supported. All this really means is that new block level elements 
-introduced in the HTML5 spec are now properly recognized as raw HTML. As
-valid  HTML5 can consist of either HTML4 or XHTML1, there is no need to add a
-new HTML5  searializers. That said, `html5` and `xhtml5` have been added as 
-aliases of the `html4` and `xhtml1` searializers respectively.
-
-An XHTML searializer has been added. Previously, ElementTree's XML searializer 
-was being used for XHTML output. With the new searliazer we are able to avoid
-more invalid output like empty elements (i.e., `
`) which can choke 
-browsers.
-
-Improved support for Python 3.x. Now when running `setupy.py install` in 
-Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 
-is not supported due to a bug in its 2to3 tool. If you must use Python-Markdown
-with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to
-do a conversion.
-
-Methods on instances of the Markdown class that do not return results can now
-be changed allowing one to do `md.reset().convert(moretext)`.
-
-The Markdown class was refactored so that a subclass could define it's own 
-`build_parser` method which would build a completely different parser. In
-other words, one could use the basic machinery in the markdown library to 
-build a parser of a different markup language without the overhead of building
-the markdown parser and throwing it away.
-
-Import statements within markdown have been improved so that third party 
-libraries can embed the markdown library if they desire (licencing permitting).
-
-Added support for Python's `-m` command line option. You can run the markdown 
-package as a command line script. Do `python -m markdown [options] [args]`. 
-Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 
-require you to call the module directly (`markdown.__main__`) rather than
-the package (`markdown`). This does not work in Python 2.4.
-
-The commandline script has been renamed to `markdown_py` which avoids all the 
-various problems we had with previous names.  Also improved the commandline 
-script to accept input on stdin.
-
-The testing framework has been completely rebuilt using the Nose testing 
-framework. This provides a number of benefits including the ability to better
-test the builtin extensions and other options available to change the parsing 
-behavior. See the [Test Suite](test_suite.html) documentation for details.
-
-Various bug fixes have been made, which are too numerous to list here. See the 
-[commit log](https://github.com/waylan/Python-Markdown/commits/master) for a 
-complete history of the changes.
diff --git a/docs/release-2.1.0.txt b/docs/release-2.1.0.txt
new file mode 100644
index 0000000..f6c203b
--- /dev/null
+++ b/docs/release-2.1.0.txt
@@ -0,0 +1,117 @@
+Python-Markdown 2.1.0 Release Notes
+===================================
+
+We are pleased to release Python-Markdown 2.1 which makes many 
+improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. 
+While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline 
+with other implementations, some internal improvements were made to the parser, 
+a few new builtin extensions were added, and HTML5 support was added.
+
+Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out 
+of the box. In fact, the same codebase installs on Python 3.1 and 3.2 with no 
+extra work by the end user.
+
+Backwards-incompatible Changes
+------------------------------
+
+While Python-Markdown has received only minor internal changes since the last
+release, there are a few backward-incompatible changes to note:
+
+* Support had been dropped for Python 2.3. No guarantees are made that the 
+library will work in any version of Python lower than 2.4. Additionally, while 
+the library had been tested with Python 2.4, consider Python 2.4 support to be 
+depreciated. It is not likely that any future versions will continue to support
+any version of Python less than 2.5. Note that Python 3.0 is not supported due 
+to a bug in its 2to3 tool. If you must use Python-Markdown with Python 3.0, it 
+is suggested you manually use Python 3.1's 2to3 tool to do a conversion.
+
+* Python-Markdown previously accepted positional arguments on its class and
+wrapper methods. It now expects keyword arguments. Currently, the positional
+arguments should continue to work, but the solution feels hacky and may be 
+removed in a future version. All users are encouraged to use keyword arguments 
+as documented in [Using Markdown as a Python Library](using_as_module.html).
+
+* Past versions of Python-Markdown provided module level Global variables which
+controlled the behavior of a few different aspects of the parser. Those global
+variables have been replaced with attributes on the Markdown class. 
+Additionally, those attributes are settable as keyword arguments when 
+initializing a class instance. Therefore, if you were editing the global 
+variables (either by editing the source or by overriding them in your code), 
+you should now set them on the class. See 
+[Using Markdown as a Python Library](using_as_module.html) for the options 
+available.
+
+* If you have been using the [HeaderID](extensions/header_id.html) extension 
+to define custom ids on headers, you will want to switch to using the new 
+[Attribute List](extensions/attr_list.html) extension. The HeaderId extension 
+now only auto-generates ids on headers which have not already had ids defined. 
+Note that the [Extra](extensions/extra.html) extension has been switched to use 
+Attribute Lists instead of HeaderId as it did previously.
+
+* Some code was moved into the `markdown.util` namespace which was previously
+in the `markdown` namespace. Extension authors may need to adjust a few
+import statements in their extensions to work with the changes.
+
+* The commandline script name was changed to `markdown_py`. The previous name
+(`markdown`) was conflicting with people (and Linux package systems) who also
+had markdown.pl installed on there system as markdown.pl's commandline script
+was also named `markdown`. Be aware that installing Python-Markdown 2.1
+will not remove the old versions of the script with different names. You
+may want to remove them yourself as they are unlikely to work properly.
+
+What's New in Python-Markdown 2.1
+---------------------------------
+
+Three new extensions were added. [Attribute Lists](extensions/attr_list.html), 
+which was inspired by Maruku's feature of the same name, 
+[Newline to Break](extensions/nl2br.html), which was inspired by Github 
+Flavored Markdown, and [Smart Strong](extensions/smart_strong.html), which 
+fills a hole in the Extra extension.
+
+HTML5 is now supported. All this really means is that new block level elements 
+introduced in the HTML5 spec are now properly recognized as raw HTML. As
+valid  HTML5 can consist of either HTML4 or XHTML1, there is no need to add a
+new HTML5  searializers. That said, `html5` and `xhtml5` have been added as 
+aliases of the `html4` and `xhtml1` searializers respectively.
+
+An XHTML searializer has been added. Previously, ElementTree's XML searializer 
+was being used for XHTML output. With the new searliazer we are able to avoid
+more invalid output like empty elements (i.e., `
`) which can choke 
+browsers.
+
+Improved support for Python 3.x. Now when running `setupy.py install` in 
+Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 
+is not supported due to a bug in its 2to3 tool. If you must use Python-Markdown
+with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to
+do a conversion.
+
+Methods on instances of the Markdown class that do not return results can now
+be changed allowing one to do `md.reset().convert(moretext)`.
+
+The Markdown class was refactored so that a subclass could define it's own 
+`build_parser` method which would build a completely different parser. In
+other words, one could use the basic machinery in the markdown library to 
+build a parser of a different markup language without the overhead of building
+the markdown parser and throwing it away.
+
+Import statements within markdown have been improved so that third party 
+libraries can embed the markdown library if they desire (licencing permitting).
+
+Added support for Python's `-m` command line option. You can run the markdown 
+package as a command line script. Do `python -m markdown [options] [args]`. 
+Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 
+require you to call the module directly (`markdown.__main__`) rather than
+the package (`markdown`). This does not work in Python 2.4.
+
+The commandline script has been renamed to `markdown_py` which avoids all the 
+various problems we had with previous names.  Also improved the commandline 
+script to accept input on stdin.
+
+The testing framework has been completely rebuilt using the Nose testing 
+framework. This provides a number of benefits including the ability to better
+test the builtin extensions and other options available to change the parsing 
+behavior. See the [Test Suite](test_suite.html) documentation for details.
+
+Various bug fixes have been made, which are too numerous to list here. See the 
+[commit log](https://github.com/waylan/Python-Markdown/commits/master) for a 
+complete history of the changes.
diff --git a/docs/release-2.1.1.md b/docs/release-2.1.1.md
deleted file mode 100644
index 9e1bcab..0000000
--- a/docs/release-2.1.1.md
+++ /dev/null
@@ -1,7 +0,0 @@
-Python-Markdown 2.1.1 Release Notes
-===================================
-
-Python-Markdown 2.1.1 is a bug-fix release. No new features have been added.
-Most notably, a bug which caused raw HTML paring to run __very__ slowly has
-been fixed along with a few bugs which caused the parser to raise exceptions
-while parsing. For a full list of changes, see the git log.
diff --git a/docs/release-2.1.1.txt b/docs/release-2.1.1.txt
new file mode 100644
index 0000000..9e1bcab
--- /dev/null
+++ b/docs/release-2.1.1.txt
@@ -0,0 +1,7 @@
+Python-Markdown 2.1.1 Release Notes
+===================================
+
+Python-Markdown 2.1.1 is a bug-fix release. No new features have been added.
+Most notably, a bug which caused raw HTML paring to run __very__ slowly has
+been fixed along with a few bugs which caused the parser to raise exceptions
+while parsing. For a full list of changes, see the git log.
diff --git a/docs/test_suite.md b/docs/test_suite.md
deleted file mode 100644
index cf9353c..0000000
--- a/docs/test_suite.md
+++ /dev/null
@@ -1,133 +0,0 @@
-title:      Test Suite
-prev_title: Extension API
-prev_url:   extensions/api.html
-
-# Test Suite
-
-Python-Markdown comes with a test suite which uses the [Nose][] testing
-framework.The test suite primarily serves to ensure that new bugs are not
-introduced as existing bugs are patched or new features are added. It also
-allows Python-Markdown to be tested with the tests from other implementations
-such as John Gruber's [Perl][] implementation or Michel Fortin's [PHP][]
-implementation.
-
-The test suite can be run by calling the `run_tests.py` command at the root of
-the distribution tarball or by calling the `nosetests` command directly. Either
-way, Nose will need to be installed on your system first (run `easy_install
-nose`). Any standard nosetests config options can be passed in on the command
-line (i.e.: verbosity level or use of a plugin like coverage).
-
-Additionally, a nicely formatted HTML report of all output is written to a
-temporary file in `tmp/test-output.html`. Open the file in a browser to view
-the report.
-
-The test suite contains three kinds of tests: Markdown Syntax Tests, Unit
-Tests, and Doc Tests.
-
-# Markdown Syntax Tests
-
-The Syntax Tests are in the various directories contained within the 'tests'
-directory of the packaged tarball. Each test consists of a matching pair of txt
-and html files. The txt file contains a snippet of Markdown source text
-formated for a specific syntax feature and the html file contains the expected
-HTML output of that snippet. When the test suite is run, each txt file is run
-through Markdown and the output is compared with the html file as a separate
-Unit Test.
-
-In fact, this is the primary reason for using Nose, it gives us an easy way to
-treat each of these tests as a separate unit test which is reported on
-separately. Additionally, with the help of a couple custom Nose plugins which
-are included with the Markdown Test Suite, we are able to get back an easy to
-read diff of the actual output compared to expected output when a test fails.
-
-Here is some sample output with a test that is failing because of some
-insignificant white space differences:
-
-    $ ./run-tests.py
-    ..........................................................M...........
-    ............................SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
-    SSSSSSSSSS.................S..........................................
-    .........
-    ======================================================================
-    MarkdownSyntaxError: TestSyntax: "misc/lists3"
-    ----------------------------------------------------------------------
-    MarkdownSyntaxError: Output from "/home/waylan/code/python-markdown/te
-    sts/misc/lists3.txt" failed to match expected output.
-
-    --- /home/waylan/code/python-markdown/tests/misc/lists3.html 
-    +++ actual_output.html 
-    @@ -1,5 +1,5 @@ 
-     
     
-     
  • blah blah blah 
-    -sdf asdf asdf asdf asdf 
-    -asda asdf asdfasd
    •  
-    +    sdf asdf asdf asdf asdf 
-    +    asda asdf asdfasd 
-     

-
-    ---------------------------------------------------------------------- 
-    Ran 219 tests in 7.698s
-
-    FAILED (MarkdownSyntaxError=1, SKIP=53)
-
-Note that 219 tests were run, one of which failed with a `MarkdownSyntaxError`.
-Only Markdown Syntax Tests should fail with a `MarkdownSyntaxError`. Nose then
-formats the error reports for `MarkdownSyntaxError`s so that they only include
-useful information. Namely the txt file which failed and a unified diff showing
-the failure. Without the plugin, you would also get a useless traceback showing
-how the code stepped through the test framework, but nothing about how Markdown
-actually ran.
-
-If, on the other hand, a Syntax Test failed because some other exception gets
-raised by either Markdown or the test suite, then that would be reported as per
-a normal unit test failure with the appropriate traceback for debugging
-purposes.
-
-### Syntax Test Config Settings
-
-The other thing to note about the above example is that 53 tests were skipped.
-Those tests have been explicitly configured to be skipped as they are primarily
-tests from either PHP or Perl which are known to fail for various reasons. In
-fact, a number of different configuration settings can be set for any specific
-test.
-
-Each Syntax Test directory contains a `test.cfg` file in the ini format. The
-file may contain a separate section for each txt file named exactly as the file
-is named minus the file extension (i.e.; the section for a test in `foo.txt`
-would be `[foo]`). All settings are optional. Default settings for the entire
-directory can be set under the `[DEFAULT]` section (must be all caps). Any
-settings under a specific file section will override anything in the
-`[DEFAULT]` section for that specific test only.
-
-Below are each of the config options available and the defaults used when they
-are not explicitly set.
-
-* `normalize`: Switches whitespace normalization of the test output on or off. 
-  Defaults to `0` (off). Note: This requires that [uTidylib] be installed on 
-  the system. Otherwise the test will be skipped, regardless of any other 
-  settings.  
-* `skip`: Switches skipping of the test on and off. Defaults to `0` (off).  
-* `input_ext`: Extension of input file. Defaults to `.txt`. Useful for tests 
-  from other implementations.
-* `output_ext`: Extension of output file. Defaults to `.html`. Useful for tests
-  from other implementations.
-* Any keyword arguement accepted my Markdown. If not set, Markdown's defaults
-  are used. 
-
-## Unit Tests
-
-All Unit Tests shipped with Python-Markdown are standard Python Unit Tests and
-are currently all contained in `tests/test_apis.py`. Standard discovery methods
-are used to find and run the tests. Therefor, when writing new tests, those
-standards and naming conventions should be followed.
-
-## Doc Tests
-
-Some Python-Markdown extensions also include standard Python doctests, which
-are discovered and run in the standard manner; one Unit Test for each file.
-
-
-[Nose]: http://somethingaboutorange.com/mrl/projects/nose/ 
-[Perl]: http://daringfireball.net/projects/markdown/ 
-[PHP]: http://michelf.com/projects/php-markdown/ 
-[uTidylib]: http://utidylib.berlios.de/
diff --git a/docs/test_suite.txt b/docs/test_suite.txt
new file mode 100644
index 0000000..cf9353c
--- /dev/null
+++ b/docs/test_suite.txt
@@ -0,0 +1,133 @@
+title:      Test Suite
+prev_title: Extension API
+prev_url:   extensions/api.html
+
+# Test Suite
+
+Python-Markdown comes with a test suite which uses the [Nose][] testing
+framework.The test suite primarily serves to ensure that new bugs are not
+introduced as existing bugs are patched or new features are added. It also
+allows Python-Markdown to be tested with the tests from other implementations
+such as John Gruber's [Perl][] implementation or Michel Fortin's [PHP][]
+implementation.
+
+The test suite can be run by calling the `run_tests.py` command at the root of
+the distribution tarball or by calling the `nosetests` command directly. Either
+way, Nose will need to be installed on your system first (run `easy_install
+nose`). Any standard nosetests config options can be passed in on the command
+line (i.e.: verbosity level or use of a plugin like coverage).
+
+Additionally, a nicely formatted HTML report of all output is written to a
+temporary file in `tmp/test-output.html`. Open the file in a browser to view
+the report.
+
+The test suite contains three kinds of tests: Markdown Syntax Tests, Unit
+Tests, and Doc Tests.
+
+# Markdown Syntax Tests
+
+The Syntax Tests are in the various directories contained within the 'tests'
+directory of the packaged tarball. Each test consists of a matching pair of txt
+and html files. The txt file contains a snippet of Markdown source text
+formated for a specific syntax feature and the html file contains the expected
+HTML output of that snippet. When the test suite is run, each txt file is run
+through Markdown and the output is compared with the html file as a separate
+Unit Test.
+
+In fact, this is the primary reason for using Nose, it gives us an easy way to
+treat each of these tests as a separate unit test which is reported on
+separately. Additionally, with the help of a couple custom Nose plugins which
+are included with the Markdown Test Suite, we are able to get back an easy to
+read diff of the actual output compared to expected output when a test fails.
+
+Here is some sample output with a test that is failing because of some
+insignificant white space differences:
+
+    $ ./run-tests.py
+    ..........................................................M...........
+    ............................SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
+    SSSSSSSSSS.................S..........................................
+    .........
+    ======================================================================
+    MarkdownSyntaxError: TestSyntax: "misc/lists3"
+    ----------------------------------------------------------------------
+    MarkdownSyntaxError: Output from "/home/waylan/code/python-markdown/te
+    sts/misc/lists3.txt" failed to match expected output.
+
+    --- /home/waylan/code/python-markdown/tests/misc/lists3.html 
+    +++ actual_output.html 
+    @@ -1,5 +1,5 @@ 
+     
     
+     
  • blah blah blah 
+    -sdf asdf asdf asdf asdf 
+    -asda asdf asdfasd
    •  
+    +    sdf asdf asdf asdf asdf 
+    +    asda asdf asdfasd 
+     

+
+    ---------------------------------------------------------------------- 
+    Ran 219 tests in 7.698s
+
+    FAILED (MarkdownSyntaxError=1, SKIP=53)
+
+Note that 219 tests were run, one of which failed with a `MarkdownSyntaxError`.
+Only Markdown Syntax Tests should fail with a `MarkdownSyntaxError`. Nose then
+formats the error reports for `MarkdownSyntaxError`s so that they only include
+useful information. Namely the txt file which failed and a unified diff showing
+the failure. Without the plugin, you would also get a useless traceback showing
+how the code stepped through the test framework, but nothing about how Markdown
+actually ran.
+
+If, on the other hand, a Syntax Test failed because some other exception gets
+raised by either Markdown or the test suite, then that would be reported as per
+a normal unit test failure with the appropriate traceback for debugging
+purposes.
+
+### Syntax Test Config Settings
+
+The other thing to note about the above example is that 53 tests were skipped.
+Those tests have been explicitly configured to be skipped as they are primarily
+tests from either PHP or Perl which are known to fail for various reasons. In
+fact, a number of different configuration settings can be set for any specific
+test.
+
+Each Syntax Test directory contains a `test.cfg` file in the ini format. The
+file may contain a separate section for each txt file named exactly as the file
+is named minus the file extension (i.e.; the section for a test in `foo.txt`
+would be `[foo]`). All settings are optional. Default settings for the entire
+directory can be set under the `[DEFAULT]` section (must be all caps). Any
+settings under a specific file section will override anything in the
+`[DEFAULT]` section for that specific test only.
+
+Below are each of the config options available and the defaults used when they
+are not explicitly set.
+
+* `normalize`: Switches whitespace normalization of the test output on or off. 
+  Defaults to `0` (off). Note: This requires that [uTidylib] be installed on 
+  the system. Otherwise the test will be skipped, regardless of any other 
+  settings.  
+* `skip`: Switches skipping of the test on and off. Defaults to `0` (off).  
+* `input_ext`: Extension of input file. Defaults to `.txt`. Useful for tests 
+  from other implementations.
+* `output_ext`: Extension of output file. Defaults to `.html`. Useful for tests
+  from other implementations.
+* Any keyword arguement accepted my Markdown. If not set, Markdown's defaults
+  are used. 
+
+## Unit Tests
+
+All Unit Tests shipped with Python-Markdown are standard Python Unit Tests and
+are currently all contained in `tests/test_apis.py`. Standard discovery methods
+are used to find and run the tests. Therefor, when writing new tests, those
+standards and naming conventions should be followed.
+
+## Doc Tests
+
+Some Python-Markdown extensions also include standard Python doctests, which
+are discovered and run in the standard manner; one Unit Test for each file.
+
+
+[Nose]: http://somethingaboutorange.com/mrl/projects/nose/ 
+[Perl]: http://daringfireball.net/projects/markdown/ 
+[PHP]: http://michelf.com/projects/php-markdown/ 
+[uTidylib]: http://utidylib.berlios.de/
-- 
cgit v1.2.3