Switch docs to mkdocs

8 files changed, 1042 insertions, 0 deletions

diff --git a/docs/change_log/index.md b/docs/change_log/index.md
new file mode 100644
index 0000000..c3100a6
--- /dev/null
+++ b/docs/change_log/index.md
@@ -0,0 +1,212 @@
+title:      Change Log
+
+Python-Markdown Change Log
+=========================
+
+Apr 20, 2015: Released version 2.6.2 (a bug-fix release).
+
+Mar 8, 2015: Released version 2.6.1 (a bug-fix release). The (new)
+`yaml` option has been removed from the Meta-Data Extension as it was buggy
+(see [#390](https://github.com/waylan/Python-Markdown/issues/390)).
+
+Feb 19, 2015: Released version 2.6 ([Notes](release-2.6.md)).
+
+Nov 19, 2014: Released version 2.5.2 (a bug-fix release).
+
+Sept 26, 2014: Released version 2.5.1 (a bug-fix release).
+
+Sept 12, 2014: Released version 2.5.0 ([Notes](release-2.5.md)).
+
+Feb 16, 2014: Released version 2.4.0 ([Notes](release-2.4.md)).
+
+Mar 22, 2013: Released version 2.3.1 (a bug-fix release).
+
+Mar 14, 2013: Released version 2.3.0 ([Notes](release-2.3.md))
+
+Nov 4, 2012: Released version 2.2.1 (a bug-fix release).
+
+Jul 5, 2012: Released version 2.2.0 ([Notes](release-2.2.md)).
+
+Jan 22, 2012: Released version 2.1.1 (a bug-fix release).
+
+Nov 24, 2011: Released version 2.1.0 ([Notes](release-2.1.md)).
+
+Oct 7, 2009: Released version 2.0.3. (a bug-fix release).
+
+Sept 28, 2009: Released version 2.0.2 (a bug-fix release).
+
+May 20, 2009: Released version 2.0.1 (a bug-fix release).
+
+Mar 30, 2009: Released version 2.0 ([Notes](release-2.0.md)).
+
+Mar 8, 2009: Release Candidate 2.0-rc-1.
+
+Feb 2009: Added support for multi-level lists to new Blockprocessors.
+
+Jan 2009: Added HTML 4 output as an option (thanks Eric Abrahamsen)
+
+Nov 2008: Added Definition List ext. Replaced old core with Blockprocessors.
+Broken up into multiple files.
+
+Oct 2008: Changed logging behavior to work better with other systems.
+Refactored tree traversing. Added `treap` implementation, then replaced with
+OrderedDict. Renamed various processors to better reflect what they actually
+do. Refactored footnote ext to match PHP Extra's output.
+
+Sept 2008: Moved `prettifyTree` to a Postprocessor, replaced WikiLink ext
+with WikiLinks (note the s) ext (uses bracketed links instead of CamelCase)
+and various bug fixes.
+
+August 18 2008: Reorganized directory structure. Added a 'docs' directory
+and moved all extensions into a 'markdown-extensions' package.
+Added additional documentation and a few bug fixes. (v2.0-beta)
+
+August 4 2008: Updated included extensions to ElementTree. Added a
+separate command line script. (v2.0-alpha)
+
+July 2008: Switched from home-grown NanoDOM to ElementTree and
+various related bugs (thanks Artem Yunusov).
+
+June 2008: Fixed issues with nested inline patterns and cleaned
+up testing framework (thanks Artem Yunusov).
+
+May 2008: Added a number of additional extensions to the
+distribution and other minor changes. Moved repository to git from svn.
+
+Mar 2008: Refactored extension API to accept either an
+extension name (as a string) or an instance of an extension
+(Thanks David Wolever). Fixed various bugs and added doc strings.
+
+Feb 2008: Various bug-fixes mostly regarding extensions.
+
+Feb 18, 2008: Version 1.7.
+
+Feb 13, 2008: A little code cleanup and better documentation
+and inheritance for Preprocessors/Postprocessors.
+
+Feb 9, 2008: Double-quotes no longer HTML escaped and raw HTML
+honors `<?foo>`, `<@foo>`, and `<%foo>` for those who run markdown on
+template syntax.
+
+Dec 12, 2007: Updated docs. Removed encoding argument from Markdown
+and markdown as per list discussion. Clean up in prep for 1.7.
+
+Nov 29, 2007: Added support for images inside links. Also fixed
+a few bugs in the footnote extension.
+
+Nov 19, 2007: `message` now uses python's logging module. Also removed
+limit imposed by recursion in `_process_section()`. You can now parse as
+long of a document as your memory can handle.
+
+Nov 5, 2007: Moved `safe_mode` code to a `textPostprocessor` and added
+escaping option.
+
+Nov 3, 2007: Fixed convert method to accept empty strings.
+
+Oct 30, 2007: Fixed `BOM` removal (thanks Malcolm Tredinnick). Fixed
+infinite loop in bracket regular expression for inline links.
+
+Oct 11, 2007: `LineBreaks` is now an `inlinePattern`. Fixed `HR` in
+blockquotes. Refactored `_processSection` method (see tracker #1793419).
+
+Oct 9, 2007: Added `textPreprocessor` (from 1.6b).
+
+Oct 8, 2008: Fixed Lazy Blockquote. Fixed code block on first line.
+Fixed empty inline image link.
+
+Oct 7, 2007: Limit recursion on inline patterns. Added a 'safe' tag
+to `htmlStash`.
+
+March 18, 2007: Fixed or merged a bunch of minor bugs, including
+multi-line comments and markup inside links. (Tracker #s: 1683066,
+1671153, 1661751, 1627935, 1544371, 1458139.) -> v. 1.6b
+
+Oct 10, 2006: Fixed a bug that caused some text to be lost after
+comments.  Added "safe mode" (user's HTML tags are removed).
+
+Sept 6, 2006: Added exception for PHP tags when handling HTML blocks.
+
+August 7, 2006: Incorporated Sergej Chodarev's patch to fix a problem
+with ampersand normalization and HTML blocks.
+
+July 10, 2006: Switched to using `optparse`.  Added proper support for
+Unicode.
+
+July 9, 2006: Fixed the `<!--@address.com>` problem (Tracker #1501354).
+
+May 18, 2006: Stopped catching unquoted titles in reference links.
+Stopped creating blank headers.
+
+May 15, 2006: A bug with lists, recursion on block-level elements,
+run-in headers, spaces before headers, Unicode input (thanks to Aaron
+Swartz). Sourceforge tracker #s: 1489313, 1489312, 1489311, 1488370,
+1485178, 1485176. (v. 1.5)
+
+Mar. 24, 2006: Switched to a not-so-recursive algorithm with
+`_handleInline`.  (Version 1.4)
+
+Mar. 15, 2006: Replaced some instance variables with class variables
+(a patch from Stelios Xanthakis).  Chris Clark's new regexps that do
+not trigger mid-word underlining.
+
+Feb. 28, 2006: Clean-up and command-line handling by Stewart
+Midwinter. (Version 1.3)
+
+Feb. 24, 2006: Fixed a bug with the last line of the list appearing
+again as a separate paragraph.  Incorporated Chris Clark's "mail-to"
+patch.  Added support for `<br />` at the end of lines ending in two or
+more spaces.  Fixed a crashing bug when using `ImageReferencePattern`.
+Added several utility methods to `Nanodom`.  (Version 1.2)
+
+Jan. 31, 2006: Added `hr` and `hr/` to BLOCK_LEVEL_ELEMENTS and
+changed `<hr/>` to `<hr />`.  (Thanks to Sergej Chodarev.)
+
+Nov. 26, 2005: Fixed a bug with certain tabbed lines inside lists
+getting wrapped in `<pre><code>`.  (v. 1.1)
+
+Nov. 19, 2005: Made `<!...`, `<?...`, etc. behave like block-level
+HTML tags.
+
+Nov. 14, 2005: Added entity code and email auto-link fix by Tiago
+Cogumbreiro.  Fixed some small issues with backticks to get 100%
+compliance with John's test suite.  (v. 1.0)
+
+Nov. 7, 2005: Added an `unlink` method for documents to aid with memory
+collection (per Doug Sauder's suggestion).
+
+Oct. 29, 2005: Restricted a set of HTML tags that get treated as
+block-level elements.
+
+Sept. 18, 2005: Refactored the whole script to make it easier to
+customize it and made footnote functionality into an extension.
+(v. 0.9)
+
+Sept. 5, 2005: Fixed a bug with multi-paragraph footnotes.  Added
+attribute support.
+
+Sept. 1, 2005: Changed the way headers are handled to allow inline
+syntax in headers (e.g. links) and got the lists to use p-tags
+correctly (v. 0.8)
+
+Aug. 29, 2005: Added flexible tabs, fixed a few small issues, added
+basic support for footnotes.  Got rid of xml.dom.minidom and added
+pretty-printing. (v. 0.7)
+
+Aug. 13, 2005: Fixed a number of small bugs in order to conform to the
+test suite.  (v. 0.6)
+
+Aug. 11, 2005: Added support for inline HTML and entities, inline
+images, auto-links, underscore emphasis. Cleaned up and refactored the
+code, added some more comments.
+
+Feb. 19, 2005: Rewrote the handling of high-level elements to allow
+multi-line list items and all sorts of nesting.
+
+Feb. 3, 2005: Reference-style links, single-line lists, backticks,
+escape, emphasis in the beginning of the paragraph.
+
+Nov. 2004: Added links, blockquotes, HTML blocks to Manfred
+Stienstra's code
+
+Apr. 2004: Manfred's version at <http://www.dwerg.net/projects/markdown/>
+
diff --git a/docs/change_log/release-2.0.md b/docs/change_log/release-2.0.md
new file mode 100644
index 0000000..78518b8
--- /dev/null
+++ b/docs/change_log/release-2.0.md
@@ -0,0 +1,69 @@
+title:      Release Notes for v2.0
+
+Python-Markdown 2.0 Release Notes
+=================================
+
+We are happy to release Python-Markdown 2.0, which has been over a year in the 
+making. We have rewritten significant portions of the code, dramatically 
+extending the extension API, increased performance, and added numerous 
+extensions to the distribution (including an extension that mimics PHP Markdown
+Extra), all while maintaining backward compatibility with the end user API in
+version 1.7.
+
+Python-Markdown supports Python versions 2.3, 2.4, 2.5, and 2.6. We have even 
+released a version converted to Python 3.0!
+
+Backwards-incompatible Changes
+------------------------------
+
+While Python-Markdown has experienced numerous internal changes, those changes 
+should only affect extension authors. If you have not written your own 
+extensions, then you should not need to make any changes to your code. 
+However, you may want to ensure that any third party extensions you are using
+are compatible with the new API.
+
+The new extension API is fully [documented](../extensions/api.md) in the docs. 
+Below is a summary of the significant changes:
+
+* The old home-grown NanoDOM has been replaced with ElementTree. Therefore all
+  extensions must use ElementTree rather than the old NanoDOM.
+* The various processors and patterns are now stored with OrderedDicts rather 
+  than lists. Any code adding processors and/or patterns into Python-Markdown 
+  will need to be adjusted to use the new API using OrderedDicts.
+* The various types of processors available have been either combined, added, 
+  or removed. Ensure that your processors match the currently supported types.
+
+What's New in Python-Markdown 2.0
+---------------------------------
+
+Thanks to the work of Artem Yunusov as part of GSoC 2008, Python-Markdown uses
+ElementTree internally to build the (X)HTML document from markdown source text.
+This has resolved various issues with the older home-grown NanoDOM and made
+notable increases in performance.
+
+Artem also refactored the Inline Patterns to better support nested patterns 
+which has resolved many inconsistencies in Python-Markdown's parsing of the 
+markdown syntax.
+
+The core parser had been completely rewritten, increasing performance and, for 
+the first time, making it possible to override/add/change the way block level
+content is parsed.
+
+Python-Markdown now parses markdown source text more closely to the other 
+popular implementations (Perl, PHP, etc.) than it ever has before. With the
+exception of a few minor insignificant differences, any difference should be
+considered a bug, rather than a limitation of the parser.
+
+The option to return HTML4 output as apposed to XHTML has been added. In 
+addition, extensions should be able to easily add additional output formats.
+
+As part of implementing markdown in the Dr. Project project (a Trac fork), among
+other things, David Wolever refactored the "extension" keyword so that it
+accepts either the extension names as strings or instances of extensions. This
+makes it possible to include multiple extensions in a single module.
+
+Numerous extensions are included in the distribution by default. See
+[available_extensions](../extensions/index.md) for a complete list.
+
+See the [Change Log](index.md) for a full list of changes.
+
diff --git a/docs/change_log/release-2.1.md b/docs/change_log/release-2.1.md
new file mode 100644
index 0000000..5dcfe61
--- /dev/null
+++ b/docs/change_log/release-2.1.md
@@ -0,0 +1,118 @@
+title:      Release Notes for v2.1
+
+Python-Markdown 2.1 Release Notes
+=================================
+
+We are pleased to release Python-Markdown 2.1 which makes many 
+improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. 
+While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline 
+with other implementations, some internal improvements were made to the parser, 
+a few new built-in extensions were added, and HTML5 support was added.
+
+Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out 
+of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no 
+extra work by the end user.
+
+Backwards-incompatible Changes
+------------------------------
+
+While Python-Markdown has received only minor internal changes since the last
+release, there are a few backward-incompatible changes to note:
+
+* Support had been dropped for Python 2.3. No guarantees are made that the 
+library will work in any version of Python lower than 2.4. Additionally, while 
+the library had been tested with Python 2.4, consider Python 2.4 support to be 
+depreciated. It is not likely that any future versions will continue to support
+any version of Python less than 2.5. Note that Python 3.0 is not supported due 
+to a bug in its 2to3 tool. If you must use Python-Markdown with Python 3.0, it 
+is suggested you manually use Python 3.1's 2to3 tool to do a conversion.
+
+* Python-Markdown previously accepted positional arguments on its class and
+wrapper methods. It now expects keyword arguments. Currently, the positional
+arguments should continue to work, but the solution feels hacky and may be 
+removed in a future version. All users are encouraged to use keyword arguments 
+as documented in the [Library Reference](../reference.md).
+
+* Past versions of Python-Markdown provided module level Global variables which
+controlled the behavior of a few different aspects of the parser. Those global
+variables have been replaced with attributes on the Markdown class. 
+Additionally, those attributes are settable as keyword arguments when 
+initializing a class instance. Therefore, if you were editing the global 
+variables (either by editing the source or by overriding them in your code), 
+you should now set them on the class. See the 
+[Library Reference](../reference.md) for the options available.
+
+* If you have been using the HeaderId extension 
+to define custom ids on headers, you will want to switch to using the new 
+Attribute List extension. The HeaderId extension 
+now only auto-generates ids on headers which have not already had ids defined. 
+Note that the Extra extension has been switched to use 
+Attribute Lists instead of HeaderId as it did previously.
+
+* Some code was moved into the `markdown.util` namespace which was previously
+in the `markdown` namespace. Extension authors may need to adjust a few
+import statements in their extensions to work with the changes.
+
+* The command line script name was changed to `markdown_py`. The previous name
+(`markdown`) was conflicting with people (and Linux package systems) who also
+had markdown.pl installed on there system as markdown.pl's command line script
+was also named `markdown`. Be aware that installing Python-Markdown 2.1
+will not remove the old versions of the script with different names. You
+may want to remove them yourself as they are unlikely to work properly.
+
+What's New in Python-Markdown 2.1
+---------------------------------
+
+Three new extensions were added. Attribute Lists, 
+which was inspired by Maruku's feature of the same name, 
+Newline to Break, which was inspired by GitHub 
+Flavored Markdown, and Smart Strong, which 
+fills a hole in the Extra extension.
+
+HTML5 is now supported. All this really means is that new block level elements 
+introduced in the HTML5 spec are now properly recognized as raw HTML. As
+valid  HTML5 can consist of either HTML4 or XHTML1, there is no need to add a
+new HTML5  serializers. That said, `html5` and `xhtml5` have been added as 
+aliases of the `html4` and `xhtml1` serializers respectively.
+
+An XHTML serializer has been added. Previously, ElementTree's XML serializer 
+was being used for XHTML output. With the new serializer we are able to avoid
+more invalid output like empty elements (i.e., `<p />`) which can choke 
+browsers.
+
+Improved support for Python 3.x. Now when running `setupy.py install` in 
+Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 
+is not supported due to a bug in its 2to3 tool. If you must use Python-Markdown
+with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to
+do a conversion.
+
+Methods on instances of the Markdown class that do not return results can now
+be changed allowing one to do `md.reset().convert(moretext)`.
+
+The Markdown class was refactored so that a subclass could define it's own 
+`build_parser` method which would build a completely different parser. In
+other words, one could use the basic machinery in the markdown library to 
+build a parser of a different markup language without the overhead of building
+the markdown parser and throwing it away.
+
+Import statements within markdown have been improved so that third party 
+libraries can embed the markdown library if they desire (licensing permitting).
+
+Added support for Python's `-m` command line option. You can run the markdown 
+package as a command line script. Do `python -m markdown [options] [args]`. 
+Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 
+require you to call the module directly (`markdown.__main__`) rather than
+the package (`markdown`). This does not work in Python 2.4.
+
+The command line script has been renamed to `markdown_py` which avoids all the 
+various problems we had with previous names.  Also improved the command line 
+script to accept input on `stdin`.
+
+The testing framework has been completely rebuilt using the Nose testing 
+framework. This provides a number of benefits including the ability to better
+test the built-in extensions and other options available to change the parsing 
+behavior. See the [Test Suite](../test_suite.md) documentation for details.
+
+Various bug fixes have been made, which are too numerous to list here. See the 
+[commit log](https://github.com/waylan/Python-Markdown/commits/master) for a 
+complete history of the changes.
diff --git a/docs/change_log/release-2.2.md b/docs/change_log/release-2.2.md
new file mode 100644
index 0000000..a5c6787
--- /dev/null
+++ b/docs/change_log/release-2.2.md
@@ -0,0 +1,64 @@
+title:      Release Notes for v2.2

+

+Python-Markdown 2.2 Release Notes

+=================================

+

+We are pleased to release Python-Markdown 2.2 which makes improvements on 2.1. 

+While 2.2 is primarily a bug fix release, some internal improvements were made 

+to the parser, and a few security issues were resolved.

+

+Python-Markdown supports Python versions 2.5, 2.6, 2.7, 3.1, and 3.2 out 

+of the box. 

+

+Backwards-incompatible Changes

+------------------------------

+

+While Python-Markdown has received only minor internal changes since the last

+release, there are a few backward-incompatible changes to note:

+

+* Support had been dropped for Python 2.4. No guarantees are made that the 

+library will work in any version of Python lower than 2.5. Additionally, while 

+the library had been tested with Python 2.5, consider Python 2.5 support to be 

+depreciated. It is not likely that any future versions will continue to support

+any version of Python less than 2.6.

+

+* For many years Python-Markdown has identified `<ins>` and `<del>` tags in 

+raw HTML input as block level tags. As they are actually inline level tags,

+this behavior has been changed. This may result in slightly different output.

+While in most cases, the new output is more correct, there may be a few edge

+cases where a document author has relied on the previous incorrect behavior.

+It is likely that a few adjustments may need to be made to those documents.

+

+* The behavior of the `enable_attributes` keyword has been slightly altered.

+If authors have been using attributes in documents with `safe_mode` on, those 

+attributes will no longer be parsed unless `enable_attributes` is explicitly

+set to `True`. This change was made to prevent untrusted authors from injecting

+potentially harmful JavaScript in documents. This change had no effect when 

+not in `safe_mode`.

+

+What's New in Python-Markdown 2.2

+---------------------------------

+

+The docs were refactored and can now be found at 

+<http://packages.python.org/Markdown/>. The docs are now maintained in the

+Repository and are generated by the `setup.py build_docs` command.

+

+The Sane_Lists

+extension was added. The Sane Lists Extension alters the behavior of the 

+Markdown List syntax to be less surprising by not allowing the mixing of list

+types. In other words, an ordered list will not continue when an unordered list

+item is encountered and vice versa.

+

+Markdown now excepts a full path to an extension module. In other words, your

+extensions no longer need to be in the primary namespace (and start with `mdx_`)

+for Markdown to find them. Just do `Markdown(extension=['path.to.some.module'])`.

+As long as the provided module contains a compatible extension, the extension

+will be loaded.

+

+The BlockParser API was slightly altered to allow `blockprocessor.run` to return

+`True` or `False` which provides more control to the block processor loop from 

+within any Blockprocessor instance.

+

+Various bug fixes have been made. See the 

+[commit log](https://github.com/waylan/Python-Markdown/commits/master) 

+for a complete history of the changes.

diff --git a/docs/change_log/release-2.3.md b/docs/change_log/release-2.3.md
new file mode 100644
index 0000000..52cc4aa
--- /dev/null
+++ b/docs/change_log/release-2.3.md
@@ -0,0 +1,82 @@
+title:      Release Notes for v2.3
+
+Python-Markdown 2.3 Release Notes
+=================================
+
+We are pleased to release Python-Markdown 2.3 which adds one new extension,
+removes a few old (obsolete) extensions, and now runs on both Python 2 and 
+Python 3 without running the 2to3 conversion tool. See the list of changes 
+below for details.
+
+Python-Markdown supports Python versions 2.6, 2.7, 3.1, 3.2, and 3.3.
+
+Backwards-incompatible Changes
+------------------------------
+
+* Support has been dropped for Python 2.5. No guarantees are made that the
+library will work in any version of Python lower than 2.6. As all supported
+Python versions include the ElementTree library, Python-Markdown will no 
+longer try to import a third-party installation of ElementTree.
+
+* All classes are now "new-style" classes. In other words, all classes
+subclass from 'object'. While this is not likely to affect most users, 
+extension authors may need to make a few minor adjustments to their code.
+
+* "safe_mode" has been further restricted. Markdown formatted links must be
+of a known white-listed scheme when in "safe_mode" or the URL is discarded.
+The white-listed schemes are: 'HTTP', 'HTTPS', 'FTP', 'FTPS', 'MAILTO', and
+'news'. Schemeless URLs are also permitted, but are checked in other ways - 
+as they have been for some time.
+
+* The ids assigned to footnotes now contain a dash (`-`) rather than a colon
+(`:`) when `output_format` it set to `"html5"` or `"xhtml5"`. If you are making
+reference to those ids in your JavaScript or CSS and using the HTML5 output,
+you will need to update your code accordingly. No changes are necessary if
+you are outputting XHTML (the default) or HTML4.
+
+* The `force_linenos` configuration setting of the CodeHilite extension has been
+marked as **Pending Deprecation** and a new setting `linenums` has been added to
+replace it. See documentation for the CodeHilite Extension for an explanation
+of the new `linenums` setting. The new setting will honor the old 
+`force_linenos` if it is set, but it will raise a `PendingDeprecationWarning` 
+and will likely be removed in a future version of Python-Markdown.
+
+
+* The "RSS" extension has been removed and no longer ships with Python-Markdown.
+If you would like to continue using the extension (not recommended), it is 
+archived on [GitHub](https://gist.github.com/waylan/4773365).
+
+* The "HTML Tidy" Extension has been removed and no longer ships with Python-Markdown.
+If you would like to continue using the extension (not recommended), it is 
+archived on [GitHub](https://gist.github.com/waylan/5152650). Note that the 
+underlying library, uTidylib, is not Python 3 compatible. Instead, it is 
+recommended that the newer [PyTidyLib] (version 0.2.2+ for Python 3 
+comparability - install from GitHub not PyPI) be used. As the API for that 
+library is rather simple, it is recommended that the output of Markdown be 
+wrapped in a call to PyTidyLib rather than using an extension (for example: 
+`tidylib.tidy_fragment(markdown.markdown(source), options={...})`).
+
+[PyTidyLib]: http://countergram.com/open-source/pytidylib
+
+What's New in Python-Markdown 2.3
+---------------------------------
+
+* The entire code base now universally runs in Python 2 and Python 3 without
+any need for running the 2to3 conversion tool. This not only simplifies testing,
+but by using Unicode_literals, results in more consistent behavior across
+Python versions. Additionally, the relative imports (made possible in Python 2
+via absolute_import) allows the entire library to more easily be embedded in a 
+sub-directory of another project. The various files within the library will 
+still import each other properly even though 'markdown' may not be in Python's
+root namespace.
+
+* The Admonition Extension has been added, which implements [rST-style][rST] 
+admonitions in the Markdown syntax. However, be warned that this extension 
+is experimental and the syntax and behavior is still subject to change. Please 
+try it out and report bugs and/or improvements.
+
+[rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions
+
+* Various bug fixes have been made.  See the
+[commit log](https://github.com/waylan/Python-Markdown/commits/master)
+for a complete history of the changes.
diff --git a/docs/change_log/release-2.4.md b/docs/change_log/release-2.4.md
new file mode 100644
index 0000000..50cfa5a
--- /dev/null
+++ b/docs/change_log/release-2.4.md
@@ -0,0 +1,67 @@
+title:      Release Notes for v2.4
+
+Python-Markdown 2.4 Release Notes
+=================================
+
+We are pleased to release Python-Markdown 2.4 which adds one new extension
+and fixes various bugs. See the list of changes below for details.
+
+Python-Markdown supports Python versions 2.6, 2.7, 3.1, 3.2, and 3.3.
+
+Backwards-incompatible Changes
+------------------------------
+
+* The `force_linenos` configuration setting of the CodeHilite extension has been
+marked as **Deprecated**. It had previously been marked as "Pending Deprecation"
+in version 2.3 when a new setting `linenums` was added to replace it. See 
+documentation for the CodeHilite Extension for an explanation of the new 
+`linenums` setting. The new setting will honor the old `force_linenos` if it 
+is set, but `force_linenos` will raise a `DeprecationWarning` and will likely 
+be removed in a future version of Python-Markdown.
+
+* URLs are no longer percent-encoded. This improves compatibility with the
+original (written in Perl) Markdown implementation. Please percent-encode
+your URLs manually when needed.
+
+What's New in Python-Markdown 2.4
+---------------------------------
+
+* Thanks to the hard work of [Dmitry Shachnev] the Smarty Extension has been 
+added, which implements [SmartyPants] using Python-Markdown's Extension API. 
+This offers a few benefits over a third party script. The HTML does not need
+to be "tokenized" twice, no hacks are required to combine SmartyPants and
+code highlighting, and we get markdown's escaping feature for free. Please try 
+it out and report bugs and/or improvements.
+
+[Dmitry Shachnev]: https://github.com/mitya57
+[SmartyPants]: http://daringfireball.net/projects/smartypants/
+
+* The Table of Contents Extension now supports new `permalink` option
+for creating [Sphinx]-style anchor links.
+
+[Sphinx]: http://sphinx-doc.org/
+
+* It is now possible to enable Markdown formatting inside HTML blocks by
+appending `markdown=1` to opening tag attributes. See Markdown Inside HTML
+Blocks section for details. Thanks to [ryneeverett] for implementing this
+feature.
+
+[ryneeverett]: https://github.com/ryneeverett
+
+* The code blocks now support emphasizing some of the code lines. To use this
+feature, specify `hl_lines` option after language name, for example (using
+the Fenced Code Extension):
+
+        ```.python hl_lines="1 3"
+        # This line will be emphasized.
+        # This one won't.
+        # This one will be also emphasized.
+        ```
+
+    Thanks to [A. Jesse Jiryu Davis] for implementing this feature.
+
+[A. Jesse Jiryu Davis]: https://github.com/ajdavis
+
+* Various bug fixes have been made.  See the
+[commit log](https://github.com/waylan/Python-Markdown/commits/master)
+for a complete history of the changes.
diff --git a/docs/change_log/release-2.5.md b/docs/change_log/release-2.5.md
new file mode 100644
index 0000000..726abfa
--- /dev/null
+++ b/docs/change_log/release-2.5.md
@@ -0,0 +1,177 @@
+title:      Release Notes for v2.5
+
+Python-Markdown 2.5 Release Notes
+=================================
+
+We are pleased to release Python-Markdown 2.5 which adds a few new features
+and fixes various bugs. See the list of changes below for details.
+
+Python-Markdown version 2.5 supports Python versions 2.7, 3.2, 3.3, and 3.4.
+
+Backwards-incompatible Changes
+------------------------------
+
+* Python-Markdown no longer supports Python version 2.6. You must be using Python 
+  versions 2.7, 3.2, 3.3, or 3.4.
+
+[importlib]: https://pypi.python.org/pypi/importlib
+
+* The `force_linenos` configuration key on the CodeHilite Extension has been **deprecated**
+  and will raise a `KeyError` if provided. In the previous release (2.4), it was 
+  issuing a `DeprecationWarning`. The `linenums` keyword should be used 
+  instead, which provides more control of the output.
+
+* Both `safe_mode` and the associated `html_replacement_text` keywords will be deprecated 
+  in version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. The so-called
+  "safe mode" was never actually "safe" which has resulted in many people having a false 
+  sense of security when using it. As an alternative, the developers of Python-Markdown 
+  recommend that any untrusted content be passed through an HTML sanitizer (like [Bleach])
+  after being converted to HTML by markdown.
+
+    If your code previously looked like this:
+
+	    html = markdown.markdown(text, same_mode=True)
+
+	Then it is recommended that you change your code to read something like this:
+
+	    import bleach
+        html = bleach.clean(markdown.markdown(text))
+
+	If you are not interested in sanitizing untrusted text, but simply desire to escape
+	raw HTML, then that can be accomplished through an extension which removes HTML parsing:
+
+		from markdown.extensions import Extension
+
+		class EscapeHtml(Extension):
+			def extendMarkdown(self, md, md_globals):
+				del md.preprocessors['html_block']
+				del md.inlinePatterns['html']
+
+		html = markdown.markdown(text, extensions=[EscapeHtml()])
+
+	As the HTML would not be parsed with the above Extension, then the serializer will
+	escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
+
+[Bleach]: http://bleach.readthedocs.org/
+
+* Positional arguments on the `markdown.Markdown()` are pending deprecation as are
+  all except the `text` argument on the `markdown.markdown()` wrapper function.
+  Only keyword arguments should be used. For example, if your code previously
+  looked like this:
+
+         html = markdown.markdown(text, ['extra'])
+    
+	Then it is recommended that you change it to read something like this:
+
+	    html = markdown.markdown(text, extensions=['extra'])
+
+	!!! Note
+	    This change is being made as a result of deprecating `"safe_mode"` as the 
+		`safe_mode` argument was one of the positional arguments. When that argument 
+		is removed, the two arguments following it will no longer be at the correct 
+		position. It is recommended that you always use keywords when they are supported
+		for this reason.
+
+* In previous versions of Python-Markdown, the built-in extensions received
+  special status and did not require the full path to be provided. Additionally,
+  third party extensions whose name started with `"mdx_"` received the same 
+  special treatment. This behavior will be deprecated in version 2.6 and will
+  raise a **`PendingDeprecationWarning`** in 2.5. Ensure that you always use the full 
+  path to your extensions. For example, if you previously did the following:
+
+        markdown.markdown(text, extensions=['extra'])
+
+    You should change your code to the following:
+
+	    markdown.markdown(text, extensions=['markdown.extensions.extra'])
+
+    The same applies to the command line:
+
+        $ python -m markdown -x markdown.extensions.extra input.txt
+
+    See the [documentation](../reference.md#extensions) for a full explanation
+    of the current behavior.
+
+* The previously documented method of appending the extension configuration as 
+  a string to the extension name will be deprecated in Python-Markdown 
+  version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. The 
+  [`extension_configs`](../reference.md#extension_configs) keyword should 
+  be used instead. See the [documentation](../reference.md#extension-configs) 
+  for a full explanation of the current behavior.
+
+What's New in Python-Markdown 2.5
+---------------------------------
+
+*   The Smarty Extension has had a number of additional configuration settings
+    added, which allows one to define their own substitutions to better support
+    languages other than English. Thanks to [Martin Altmayer] for implementing this 
+	feature.
+
+[Martin Altmayer]:https://github.com/MartinAltmayer
+
+*   Named Extensions (strings passed to the [`extensions`][ex] keyword of 
+    `markdown.Markdown`) can now point to any module and/or Class on your PYTHONPATH. 
+	While dot notation was previously supported, a module could not be at the root of 
+	your PYTHONPATH. The name had to contain at least one dot (requiring it to be a 
+	sub-module). This restriction no longer exists. 
+
+	Additionally, a Class may be specified in the name. The class must be at the end of 
+	the name (which uses dot notation from PYTHONPATH) and be separated by a colon from 
+	the module. 
+
+	Therefore, if you were to import the class like this:
+	
+		from path.to.module import SomeExtensionClass
+
+	Then the named extension would comprise this string:
+
+		"path.to.module:SomeExtensionClass"
+	
+	This allows multiple extensions to be implemented within the same module and still 
+	accessible when the user is not able to import the extension directly (perhaps from 
+	a template filter or the command line).
+
+	This also means that extension modules are no longer required to include the 
+	`makeExtension`	function which returns an instance of the extension class. However, 
+	if the user does not specify the class name (she only provides `"path.to.module"`)
+	the extension will fail to load without the `makeExtension` function included in
+	the module. Extension authors will want to document carefully what is required to
+	load their extensions.
+
+[ex]: ../reference.md#extensions
+
+*   The Extension Configuration code has been refactored to make it a little easier 
+    for extension authors to work with configuration settings. As a result, the 
+    [`extension_configs`][ec] keyword now accepts a dictionary rather than requiring 
+    a list of tuples. A list of tuples is still supported so no one needs to change 
+    their existing code. This should also simplify the learning curve for new users.
+
+	Extension authors are encouraged to review the new methods available on the 
+	`markdown.extnesions.Extension` class for handling configuration and adjust their
+	code going forward. The included extensions provide a model for best practices.
+	See the [API] documentation for a full explanation.
+
+[ec]: ../reference.md#extension_configs
+[API]: ../extensions/api.md#configsettings
+
+*   The [Command Line Interface][cli] now accepts a `--extensions_config` (or `-c`) 
+    option which accepts a file name and passes the parsed content of a [YAML] or 
+	[JSON]   file to the [`extension_configs`][ec] keyword of the `markdown.Markdown`
+	class. The contents of the YAML or JSON must map to a Python Dictionary which 
+	matches the format required by the `extension_configs` keyword. Note that 
+	[PyYAML] is required to parse YAML files.
+
+[cli]: ../cli.md#using-extensions
+[YAML]: http://yaml.org/
+[JSON]: http://json.org/
+[PyYAML]: http://pyyaml.org/
+
+*   The Admonition Extension is no longer considered "experimental."
+
+*   There have been various refactors of the testing framework. While those changes
+    will not directly effect end users, the code is being better tested which will 
+    benefit everyone.
+
+*   Various bug fixes have been made.  See the
+    [commit log](https://github.com/waylan/Python-Markdown/commits/master)
+    for a complete history of the changes.
diff --git a/docs/change_log/release-2.6.md b/docs/change_log/release-2.6.md
new file mode 100644
index 0000000..4cd3501
--- /dev/null
+++ b/docs/change_log/release-2.6.md
@@ -0,0 +1,253 @@
+title:      Release Notes for v2.6
+
+Python-Markdown 2.6 Release Notes
+=================================
+
+We are pleased to release Python-Markdown 2.6 which adds a few new features
+and fixes various bugs. See the list of changes below for details.
+
+Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as well as PyPy.
+
+Backwards-incompatible Changes
+------------------------------
+
+### `safe_mode` Deprecated
+
+Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated 
+in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and
+`html_replacement_text` keywords will be ignored in version 2.7. The so-called
+"safe mode" was never actually "safe" which has resulted in many people having a false 
+sense of security when using it. As an alternative, the developers of Python-Markdown 
+recommend that any untrusted content be passed through an HTML sanitizer (like [Bleach])
+after being converted to HTML by markdown.
+
+If your code previously looked like this:
+
+    html = markdown.markdown(text, safe_mode=True)
+
+Then it is recommended that you change your code to read something like this:
+
+    import bleach
+    html = bleach.clean(markdown.markdown(text))
+
+If you are not interested in sanitizing untrusted text, but simply desire to escape
+raw HTML, then that can be accomplished through an extension which removes HTML parsing:
+
+    from markdown.extensions import Extension
+
+    class EscapeHtml(Extension):
+        def extendMarkdown(self, md, md_globals):
+        del md.preprocessors['html_block']
+        del md.inlinePatterns['html']
+
+    html = markdown.markdown(text, extensions=[EscapeHtml()])
+
+As the HTML would not be parsed with the above Extension, then the serializer will
+escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
+
+[Bleach]: http://bleach.readthedocs.org/
+
+### Positional Arguments Deprecated
+
+Positional arguments on the `markdown.Markdown()` class are deprecated as are
+all except the `text` argument on the `markdown.markdown()` wrapper function.
+Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an error
+in version 2.7. Only keyword arguments should be used. For example, if your code
+previously looked like this:
+
+    html = markdown.markdown(text, [SomeExtension()])
+
+Then it is recommended that you change it to read something like this:
+
+    html = markdown.markdown(text, extensions=[SomeExtension()])
+
+!!! Note
+    This change is being made as a result of deprecating `"safe_mode"` as the 
+    `safe_mode` argument was one of the positional arguments. When that argument 
+    is removed, the two arguments following it will no longer be at the correct 
+    position. It is recommended that you always use keywords when they are supported
+    for this reason.
+
+### "Shortened" Extension Names Deprecated
+
+In previous versions of Python-Markdown, the built-in extensions received
+special status and did not require the full path to be provided. Additionally,
+third party extensions whose name started with `"mdx_"` received the same 
+special treatment. This behavior is deprecated and will raise a
+**`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you
+always use the full path to your extensions. For example, if you previously
+did the following:
+
+    markdown.markdown(text, extensions=['extra'])
+
+You should change your code to the following:
+
+    markdown.markdown(text, extensions=['markdown.extensions.extra'])
+
+The same applies to the command line:
+
+    $ python -m markdown -x markdown.extensions.extra input.txt
+
+Similarly, if you have used a third party extension (for example `mdx_math`), previously
+you might have called it like this:
+
+    markdown.markdown(text, extensions=['math'])
+
+As the `"mdx"` prefix will no longer be appended, you will need to change your code
+as follows (assuming the file `mdx_math.py` is installed at the root of your PYTHONPATH):
+
+    markdown.markdown(text, extensions=['mdx_math'])
+
+Extension authors will want to update their documentation to reflect the new behavior.
+
+See the [documentation](../reference.md#extensions) for a full explanation
+of the current behavior.
+
+### Extension Configuration as Part of Extension Name Deprecated
+
+The previously documented method of appending the extension configuration options as 
+a string to the extension name is deprecated and will raise a
+**`DeprecationWarning`** in version 2.6 and an error in 2.7.
+The [`extension_configs`](../reference.md#extension_configs) keyword should 
+be used instead. See the [documentation](../reference.md#extension-configs) 
+for a full explanation of the current behavior.
+
+### HeaderId Extension Pending Deprecation
+
+The HeaderId Extension is pending deprecation and will raise a
+**`PendingDeprecationWarning`** in version 2.6. The extension will be
+deprecated in version 2.7 and raise an error in version 2.8. Use the
+Table of Contents Extension instead, which offers most of the
+features of the HeaderId Extension and more (support for meta data is missing).
+
+Extension authors who have been using the `slugify` and `unique` functions
+defined in the HeaderId Extension should note that those functions are now
+defined in the Table of Contents extension and should adjust their import
+statements accordingly (`from markdown.extensions.toc import slugify, unique`).
+
+### The `configs` Keyword is Deprecated
+
+Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class
+(and its subclasses) are deprecated. Each individual configuration option should be passed
+to the class as a keyword/value pair. For example. one might have previously initiated
+an extension subclass like this:
+
+    ext = SomeExtension(configs={'somekey': 'somevalue'})
+
+That code should be updated to pass in the options directly:
+
+    ext = SomeExtension(somekey='somevalue')
+
+Extension authors will want to note that this affects the `makeExtension` function as well.
+Previously it was common for the function to be defined as follows:
+
+    def makeExtension(configs=None):
+        return SomeExtension(configs=configs)
+
+Extension authors will want to update their code to the following instead:
+
+    def makeExtension(**kwargs):
+        return SomeExtension(**kwargs)
+
+Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next
+release. See the [Extension API][mext] documentation for more information.
+
+In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method
+and implements its own configuration handling, then the above may not apply. However, it is
+recommended that the subclass still calls the parent `__init__` method to handle configuration
+options like so:
+
+    class SomeExtension(markdown.extension.Extension):
+        def __init__(**kwargs):
+            # Do pre-config stuff here
+            # Set config defaults
+            self.config = {
+                'option1' : ['value1', 'description1'],
+                'option2' : ['value2', 'description2']
+            }
+            # Set user defined configs
+            super(MyExtension, self).__init__(**kwargs)
+            # Do post-config stuff here
+
+Note the call to `super` to get the benefits of configuration handling from the parent class.
+See the [documentation][config] for more information.
+
+[config]: ../extensions/api.md#configsettings
+[mext]: ../extensions/api.md#makeextension
+
+What's New in Python-Markdown 2.6
+---------------------------------
+
+### Official Support for PyPy
+
+Official support for [PyPy] has been added. While Python-Markdown has most likely
+worked on PyPy for some time, it is now officially supported and tested on PyPy.
+
+[PyPy]: http://pypy.org/
+
+### YAML Style Meta-Data
+
+The Meta-Data Extension now includes optional support for [YAML] style
+meta-data. By default, the YAML deliminators are recognized, however, the
+actual data is parsed as previously.  This follows the syntax of
+[MultiMarkdown], which inspired this extension.
+
+<del>Alternatively, if the `yaml` option is set, then the data is parsed as YAML.</del>
+<ins>As the `yaml` option was buggy, it was removed in 2.6.1. It is suggested that a third
+party extension be used if you want true YAML support. See [Issue #390][#390] for a full
+explanation.</ins>
+
+[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
+[YAML]: http://yaml.org/
+[#390]: https://github.com/waylan/Python-Markdown/issues/390
+
+### Table of Contents Extension Refactored
+
+The Table of Contents Extension has been refactored and some new features
+have been added.  See the documentation for a full explanation of each feature
+listed below:
+
+*   The extension now assigns the Table of Contents to the `toc` attribute of
+    the Markdown class regardless of whether a "marker" was found in the document.
+    Third party frameworks no longer need to insert a "marker," run the document
+    through Markdown, then extract the Table of Contents from the document.
+
+*   The Table of Contents Extension is now a "registered extension." Therefore, when the `reset`
+    method of the Markdown class is called, the `toc` attribute on the Markdown
+    class is cleared (set to an empty string).
+
+*   When the `marker` configuration option is set to an empty string, the parser completely
+    skips the process of searching the document for markers. This should save parsing
+    time when the Table of Contents Extension is being used only to assign ids to headers.
+
+*   A `separator` configuration option has been added allowing users to override the
+    separator character used by the slugify function.
+
+*   A `baselevel` configuration option has been added allowing users to set the base level
+    of headers in their documents (h1-h6). This allows the header levels to be
+    automatically adjusted to fit within the hierarchy of an HTML template.
+
+### Pygments can now be disabled
+
+The CodeHilite Extension has gained a new configuration option: `use_pygments`.
+The option is `True` by default, however, it allows one to turn off Pygments code
+highlighting (set to `False`) while preserving the language detection features of
+the extension. Note that Pygments language guessing is not used as that would 'use
+Pygments'. If a language is defined for a code block, it will be assigned to the 
+`<code>` tag as a class in the manner suggested by the [HTML5 spec][spec]
+(alternate output will not be entertained) and could potentially be used by a JavaScript
+library in the browser to highlight the code block.
+
+[spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
+
+### Miscellaneous
+
+Test coverage has been improved including running [flake8]. While those changes
+will not directly effect end users, the code is being better tested which will 
+benefit everyone.
+
+[flake8]: http://flake8.readthedocs.org/en/latest/
+
+Various bug fixes have been made.  See the
+[commit log](https://github.com/waylan/Python-Markdown/commits/master)
+for a complete history of the changes.