From ec46692cf5c4d5e22950bc8e7d14cb0ec327fb87 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 7 Mar 2012 09:35:40 -0500 Subject: Rename docs/*.md => docs/*.txt The documentation uses features of Python-Markdown that are not supported on GitHub and it's better to get a source view of the docs anyway. For example, that way comments and bug reports can reference a specific line of a file. Of course, it makes sense for Github to render the README, so that is left with the `.md` file extension. --- docs/extensions/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 ++++++++ 38 files changed, 1873 insertions(+), 1873 deletions(-) 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 (limited to 'docs/extensions') 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.

+
-- 
cgit v1.2.3