From faacead0dbbb1aee3bdd72597b47c7188a168a1a Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 22 Apr 2015 20:22:11 -0400 Subject: [PATCH 1/7] Switch to MKDocs This is a work in progress. I merged in 6f87b32 from the md3 branch. That branch has all of the extension docs removed, so they haven't been converted yet. And I only resolved conflicts and updated mkdocs.yml to the current MkDocs format. Addresses #601. --- INSTALL.md | 4 +- README.md | 14 +- checkspelling.sh | 8 +- docs/_template.html | 81 ---- docs/authors.md | 58 +++ docs/authors.txt | 60 --- docs/basic.css | 445 ------------------ docs/{change_log.txt => change_log/index.md} | 28 +- .../release-2.0.md} | 10 +- .../release-2.1.md} | 28 +- .../release-2.2.md} | 14 +- .../release-2.3.md} | 10 +- .../release-2.4.md} | 22 +- .../release-2.5.md} | 32 +- .../release-2.6.md} | 30 +- docs/{cli.txt => cli.md} | 13 +- docs/default.css | 261 ---------- docs/extensions/{api.txt => api.md} | 8 +- docs/extensions/index.md | 85 ++++ docs/extensions/index.txt | 87 ---- docs/favicon.ico | Bin 0 -> 15086 bytes docs/{index.txt => index.md} | 31 +- docs/{install.txt => install.md} | 10 +- docs/{reference.txt => reference.md} | 213 +++++---- docs/release-2.0.1.txt | 22 - docs/release-2.0.2.txt | 15 - docs/release-2.1.1.txt | 13 - docs/release-2.2.1.txt | 12 - docs/{siteindex.txt => siteindex.md} | 0 docs/{test_suite.txt => test_suite.md} | 0 makefile | 4 +- mkdocs.yml | 39 ++ setup.py | 156 +----- test-requirements.txt | 3 +- 34 files changed, 399 insertions(+), 1417 deletions(-) delete mode 100644 docs/_template.html create mode 100644 docs/authors.md delete mode 100644 docs/authors.txt delete mode 100644 docs/basic.css rename docs/{change_log.txt => change_log/index.md} (89%) rename docs/{release-2.0.txt => change_log/release-2.0.md} (90%) rename docs/{release-2.1.0.txt => change_log/release-2.1.md} (86%) rename docs/{release-2.2.0.txt => change_log/release-2.2.md} (87%) rename docs/{release-2.3.txt => change_log/release-2.3.md} (91%) rename docs/{release-2.4.txt => change_log/release-2.4.md} (73%) rename docs/{release-2.5.txt => change_log/release-2.5.md} (87%) rename docs/{release-2.6.txt => change_log/release-2.6.md} (91%) rename docs/{cli.txt => cli.md} (94%) delete mode 100644 docs/default.css rename docs/extensions/{api.txt => api.md} (99%) create mode 100644 docs/extensions/index.md delete mode 100644 docs/extensions/index.txt create mode 100644 docs/favicon.ico rename docs/{index.txt => index.md} (77%) rename docs/{install.txt => install.md} (88%) rename docs/{reference.txt => reference.md} (72%) delete mode 100644 docs/release-2.0.1.txt delete mode 100644 docs/release-2.0.2.txt delete mode 100644 docs/release-2.1.1.txt delete mode 100644 docs/release-2.2.1.txt rename docs/{siteindex.txt => siteindex.md} (100%) rename docs/{test_suite.txt => test_suite.md} (100%) create mode 100644 mkdocs.yml diff --git a/INSTALL.md b/INSTALL.md index 6e6ab8c74..95fbfd125 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -5,5 +5,5 @@ As an Admin/Root user on your system do: pip install markdown -Or for more specific instructions, view the documentation in `docs/install.txt` -or on the website at . +Or for more specific instructions, view the documentation in `docs/install.md` +or on the website at . diff --git a/README.md b/README.md index 5e8dc8492..0f5b673ed 100644 --- a/README.md +++ b/README.md @@ -8,23 +8,23 @@ [![BSD License](http://img.shields.io/badge/license-BSD-yellow.svg)](http://opensource.org/licenses/BSD-3-Clause) [![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-contributor%20covenant-green.svg?style=flat-square)][Code of Conduct] -This is a Python implementation of John Gruber's [Markdown][]. +This is a Python implementation of John Gruber's [Markdown][]. It is almost completely compliant with the reference implementation, -though there are a few known issues. See [Features][] for information -on what exactly is supported and what is not. Additional features are +though there are a few known issues. See [Features][] for information +on what exactly is supported and what is not. Additional features are supported by the [Available Extensions][]. [Python-Markdown]: https://pythonhosted.org/Markdown/ [Markdown]: http://daringfireball.net/projects/markdown/ -[Features]: https://pythonhosted.org/Markdown/index.html#Features -[Available Extensions]: https://pythonhosted.org/Markdown/extensions/index.html +[Features]: https://pythonhosted.org/Markdown/index/#Features +[Available Extensions]: https://pythonhosted.org/Markdown/extensions/ Documentation ------------- Installation and usage documentation is available in the `docs/` directory -of the distribution and on the project website at +of the distribution and on the project website at . See the change log at . @@ -35,7 +35,7 @@ Support You may ask for help and discuss various other issues on the [mailing list][] and report bugs on the [bug tracker][]. [mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss -[bug tracker]: http://github.com/Python-Markdown/markdown/issues +[bug tracker]: http://github.com/Python-Markdown/markdown/issues Code of Conduct --------------- diff --git a/checkspelling.sh b/checkspelling.sh index 4ae20cc85..654fef061 100755 --- a/checkspelling.sh +++ b/checkspelling.sh @@ -1,14 +1,14 @@ #!/bin/bash echo "Building docs..." -python setup.py --quiet build_docs --force +mkdocs build --clean echo "Compiling Dictionary..." aspell --lang=en create master ./tmp <.spell-dict -echo "Checking spelling...\n" +echo "Checking spelling..." let "fails=0" -for file in $(find build/docs/ -type f -name "*.html"); do +for file in $(find site/ -type f -name "*.html"); do words=$(aspell list --lang=en --mode=html --add-html-skip=code --extra-dicts=./tmp <$file) if [ "$words" ]; then uniquewords=$(tr ' ' '\n' <<< "${words[@]}" | sort -u | tr '\n' ' ') @@ -22,7 +22,7 @@ for file in $(find build/docs/ -type f -name "*.html"); do fi done rm -f ./tmp -rm -rf build +rm -rf site if [ $fails -gt 0 ]; then echo "$fails files with misspelled words." diff --git a/docs/_template.html b/docs/_template.html deleted file mode 100644 index 58e99671c..000000000 --- a/docs/_template.html +++ /dev/null @@ -1,81 +0,0 @@ - - - - -%(page_title)s - - - - -
-

Navigation

- -
- -
-
-
-
-%(body)s -
-
-
- -
-
-

Table Of Contents

- %(toc)s - -

Previous topic

-

%(prev_title)s

-

Next topic

-

%(next_title)s

-

This Page

- -
-
- -
-
- -
-

Navigation

- -
- -
© 2010-2012 Python Markdown Project
- - diff --git a/docs/authors.md b/docs/authors.md new file mode 100644 index 000000000..9b75b23cb --- /dev/null +++ b/docs/authors.md @@ -0,0 +1,58 @@ +title: Authors + +Primary Authors +=============== + +* __[Waylan Limberg](http://achinghead.com/)__ + + Waylan is the current maintainer of the code and has written much of the current + code base, included a complete refactor of the core. He started out by + authoring many of the available extensions and later was asked to join Yuri, + where he began fixing numerous bugs, adding documentation and making general + improvements to the existing code base. + + +* __[Yuri Takteyev](http://freewisdom.org/)__ + + Yuri wrote most of the code found in version 1.x while procrastinating his Ph.D. + Various pieces of his code still exist, most notably the basic structure. + +* __[Manfed Stienstra](http://www.dwerg.net/)__ + + Manfed wrote the original version of the script and is responsible for + various parts of the existing code base. + +* __Artem Yunusov__ + + Artem, who as part of a 2008 GSoC project, refactored inline patterns, + replaced the NanoDOM with ElementTree support and made various other + improvements. + +* __David Wolever__ + + David refactored the extension API and made other improvements + as he helped to integrate Markdown into Dr.Project. + +Other Contributors +================== + +The incomplete list of individuals below have provided patches or otherwise +contributed to the project in various ways. We would like to thank everyone +who has contributed to the project in any way. + +* Eric Abrahamsen +* Jeff Balogh +* Sergej Chodarev +* Chris Clark +* Tiago Cogumbreiro +* Kjell Magne Fauske +* G. Clark Haynes +* Daniel Krech +* Steward Midwinter +* Jack Miller +* Neale Pickett +* Paul Stansifer +* John Szakmeister +* Malcolm Tredinnick +* Ben Wilson +* and many others who helped by reporting bugs diff --git a/docs/authors.txt b/docs/authors.txt deleted file mode 100644 index 84c69d001..000000000 --- a/docs/authors.txt +++ /dev/null @@ -1,60 +0,0 @@ -title: Authors -prev_title: Release Notes for v2.0 -prev_url: release-2.0.html -next_title: Table of Contents -next_url: siteindex.html - -Primary Authors -=============== - -[Yuri Takteyev](http://freewisdom.org/) - -: Yuri has written much of the current code while procrastinating his Ph.D. - -[Waylan Limberg](http://achinghead.com/) - -: Waylan is the current maintainer of the code and has written much the current - code base, included a complete refactor of the core. He started out by - authoring many of the available extensions and later was asked to join Yuri, - where he began fixing numerous bugs, adding documentation and making general - improvements to the existing code base. - -Artem Yunusov - -: Artem, who as part of a 2008 GSoC project, refactored inline patterns, - replaced the NanoDOM with ElementTree support and made various other - improvements. - -[Manfed Stienstra](http://www.dwerg.net/) - -: Manfed wrote the original version of the script and is responsible for - various parts of the existing code base. - -David Wolever - -: David refactored the extension API and made other improvements - as he helped to integrate Markdown into Dr.Project. - -Other Contributors -================== - -The incomplete list of individuals below have provided patches or otherwise -contributed to the project in various ways. We would like to thank everyone -who has contributed to the project in any way. - -* Eric Abrahamsen -* Jeff Balogh -* Sergej Chodarev -* Chris Clark -* Tiago Cogumbreiro -* Kjell Magne Fauske -* G. Clark Haynes -* Daniel Krech -* Steward Midwinter -* Jack Miller -* Neale Pickett -* Paul Stansifer -* John Szakmeister -* Malcolm Tredinnick -* Ben Wilson -* and many others who helped by reporting bugs diff --git a/docs/basic.css b/docs/basic.css deleted file mode 100644 index 3f7ad8020..000000000 --- a/docs/basic.css +++ /dev/null @@ -1,445 +0,0 @@ -/** - * Sphinx stylesheet -- basic theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -/* -- main layout ----------------------------------------------------------- */ - -div.clearer { - clear: both; -} - -/* -- relbar ---------------------------------------------------------------- */ - -div.related { - width: 100%; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -/* -- sidebar --------------------------------------------------------------- */ - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.sphinxsidebar ul { - list-style: none; -} - -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -img { - border: 0; -} - -/* -- search page ----------------------------------------------------------- */ - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* -- index page ------------------------------------------------------------ */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* -- general index --------------------------------------------------------- */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -/* -- general body styles --------------------------------------------------- */ - -a.headerlink { - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -.field-list ul { - padding-left: 1em; -} - -.first { - margin-top: 0 !important; -} - -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* -- sidebars -------------------------------------------------------------- */ - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; -} - -/* -- topics ---------------------------------------------------------------- */ - -div.topic { - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* -- admonitions ----------------------------------------------------------- */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -/* -- tables ---------------------------------------------------------------- */ - -table { - border: 0 solid #dce; - border-collapse: collapse; -} - -table td, table th { - padding: 2px 5px 2px 5px; -} - -table td { - border: 1px solid #ddd; - background-color: #eef; -} - -table td p.last, table th p.last { - margin-bottom: 0; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -table th { - border: 1px solid #cac; - background-color: #ede; -} - -th { - text-align: left; - padding-right: 5px; -} - -th.head { - text-align: center; -} - -/* -- other body styles ----------------------------------------------------- */ - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -dt:target, .highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -.refcount { - color: #060; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -p.deprecated { - background-color: #ffe4e4; - border: 1px solid #f66; - padding: 7px -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -.footnote:target { - background-color: #ffa; -} - -.impl-detail { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; - border: 1px solid #ccc; -} - -.impl-detail .compound-first { - margin-top: 0; -} - -.impl-detail .compound-last { - margin-bottom: 0; -} - -/* -- code displays --------------------------------------------------------- */ - -pre { - overflow: auto; - overflow-y: hidden; -} - -code { - font-size: 1.1em; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -/* -- math display ---------------------------------------------------------- */ - -img.math { - vertical-align: middle; -} - -div.body div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -/* -- printout stylesheet --------------------------------------------------- */ - -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0 !important; - width: 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - #top-link { - display: none; - } -} diff --git a/docs/change_log.txt b/docs/change_log/index.md similarity index 89% rename from docs/change_log.txt rename to docs/change_log/index.md index c9478a2f8..8f921e1c7 100644 --- a/docs/change_log.txt +++ b/docs/change_log/index.md @@ -1,8 +1,4 @@ title: Change Log -prev_title: Test Suite -prev_url: test_suite.html -next_title: Release Notes for v2.6 -next_url: release-2.6.html Python-Markdown Change Log ========================= @@ -27,35 +23,35 @@ 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/Python-Markdown/markdown/issues/390)). -Feb 19, 2015: Released version 2.6 ([Notes](release-2.6.html)). +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.html)). +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.html)). +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.html)) +Mar 14, 2013: Released version 2.3.0 ([Notes](release-2.3.md)) -Nov 4, 2012: Released version 2.2.1 ([Notes](release-2.2.1.html)). +Nov 4, 2012: Released version 2.2.1 (a bug-fix release). -Jul 5, 2012: Released version 2.2.0 ([Notes](release-2.2.0.html)). +Jul 5, 2012: Released version 2.2.0 ([Notes](release-2.2.md)). -Jan 22, 2012: Released version 2.1.1 ([Notes](release-2.1.1.html)). +Jan 22, 2012: Released version 2.1.1 (a bug-fix release). -Nov 24, 2011: Released version 2.1.0 ([Notes](release-2.1.0.html)). +Nov 24, 2011: Released version 2.1.0 ([Notes](release-2.1.md)). -Oct 7, 2009: Released version 2.0.3. +Oct 7, 2009: Released version 2.0.3. (a bug-fix release). -Sept 28, 2009: Released version 2.0.2 ([Notes](release-2.0.2.html)). +Sept 28, 2009: Released version 2.0.2 (a bug-fix release). -May 20, 2009: Released version 2.0.1 ([Notes](release-2.0.1.html)). +May 20, 2009: Released version 2.0.1 (a bug-fix release). -Mar 30, 2009: Released version 2.0 ([Notes](release-2.0.html)). +Mar 30, 2009: Released version 2.0 ([Notes](release-2.0.md)). Mar 8, 2009: Release Candidate 2.0-rc-1. diff --git a/docs/release-2.0.txt b/docs/change_log/release-2.0.md similarity index 90% rename from docs/release-2.0.txt rename to docs/change_log/release-2.0.md index f44b0c51e..78518b887 100644 --- a/docs/release-2.0.txt +++ b/docs/change_log/release-2.0.md @@ -1,8 +1,4 @@ title: Release Notes for v2.0 -prev_title: Release Notes for v2.0.1 -prev_url: release-2.0.1.html -next_title: Authors -next_url: authors.html Python-Markdown 2.0 Release Notes ================================= @@ -26,7 +22,7 @@ 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.html) in the docs. +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 @@ -67,7 +63,7 @@ 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.html) for a complete list. +[available_extensions](../extensions/index.md) for a complete list. -See the [Change Log](change_log.html) for a full list of changes. +See the [Change Log](index.md) for a full list of changes. diff --git a/docs/release-2.1.0.txt b/docs/change_log/release-2.1.md similarity index 86% rename from docs/release-2.1.0.txt rename to docs/change_log/release-2.1.md index 43230dcd9..ad75ac986 100644 --- a/docs/release-2.1.0.txt +++ b/docs/change_log/release-2.1.md @@ -1,11 +1,7 @@ -title: Release Notes for v2.1.0 -prev_title: Release Notes for v2.1.1 -prev_url: release-2.1.1.html -next_title: Release Notes for v2.0.2 -next_url: release-2.0.2.html +title: Release Notes for v2.1 -Python-Markdown 2.1.0 Release Notes -=================================== +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. @@ -35,7 +31,7 @@ is suggested you manually use Python 3.1's 2to3 tool to do a conversion. 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.html). +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 @@ -44,13 +40,13 @@ 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.html) for the options available. +[Library Reference](../reference.md) for the options available. -* If you have been using the [HeaderId](extensions/header_id.html) extension +* 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](extensions/attr_list.html) extension. The HeaderId extension +Attribute List extension. The HeaderId extension now only auto-generates ids on headers which have not already had ids defined. -Note that the [Extra](extensions/extra.html) extension has been switched to use +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 @@ -67,10 +63,10 @@ may want to remove them yourself as they are unlikely to work properly. What's New in Python-Markdown 2.1 --------------------------------- -Three new extensions were added. [Attribute Lists](extensions/attr_list.html), +Three new extensions were added. Attribute Lists, which was inspired by Maruku's feature of the same name, -[Newline to Break](extensions/nl2br.html), which was inspired by GitHub -Flavored Markdown, and [Smart Strong](extensions/smart_strong.html), which +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 @@ -115,7 +111,7 @@ 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.html) documentation for details. +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/Python-Markdown/markdown/commits/master) for a diff --git a/docs/release-2.2.0.txt b/docs/change_log/release-2.2.md similarity index 87% rename from docs/release-2.2.0.txt rename to docs/change_log/release-2.2.md index 8b94563cd..5533eadf2 100644 --- a/docs/release-2.2.0.txt +++ b/docs/change_log/release-2.2.md @@ -1,11 +1,7 @@ -title: Release Notes for v2.2.0 -prev_title: Release Notes for v2.2.1 -prev_url: release-2.2.1.html -next_title: Release Notes for v2.1.1 -next_url: release-2.1.1.html +title: Release Notes for v2.2 -Python-Markdown 2.2.0 Release Notes -=================================== +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 @@ -40,14 +36,14 @@ 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.1 +What's New in Python-Markdown 2.2 --------------------------------- The docs were refactored and can now be found at . The docs are now maintained in the Repository and are generated by the `setup.py build_docs` command. -The [Sane_Lists](http://packages.python.org/Markdown/extensions/sane_lists.html) +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 diff --git a/docs/release-2.3.txt b/docs/change_log/release-2.3.md similarity index 91% rename from docs/release-2.3.txt rename to docs/change_log/release-2.3.md index 81c5d888e..449db6aed 100644 --- a/docs/release-2.3.txt +++ b/docs/change_log/release-2.3.md @@ -1,8 +1,4 @@ title: Release Notes for v2.3 -prev_title: Release Notes for v2.4 -prev_url: release-2.4.html -next_title: Release Notes for v2.2.1 -next_url: release-2.2.1.html Python-Markdown 2.3 Release Notes ================================= @@ -40,12 +36,11 @@ 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 +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. -[CodeHilite Extension]: extensions/codehilite.html * 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 @@ -75,12 +70,11 @@ 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] +* 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. -[Admonition Extension]: extensions/admonition.html [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions * Various bug fixes have been made. See the diff --git a/docs/release-2.4.txt b/docs/change_log/release-2.4.md similarity index 73% rename from docs/release-2.4.txt rename to docs/change_log/release-2.4.md index f1d00af47..c6a3034e4 100644 --- a/docs/release-2.4.txt +++ b/docs/change_log/release-2.4.md @@ -1,8 +1,4 @@ title: Release Notes for v2.4 -prev_title: Release Notes for v2.5 -prev_url: release-2.5.html -next_title: Release Notes for v2.3 -next_url: release-2.3.html Python-Markdown 2.4 Release Notes ================================= @@ -18,13 +14,11 @@ 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 +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. -[CodeHilite Extension]: extensions/code_hilite.html - * 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. @@ -32,7 +26,7 @@ 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 +* 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 @@ -40,26 +34,23 @@ 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 -[Smarty Extension]: extensions/smarty.html [SmartyPants]: http://daringfireball.net/projects/smartypants/ -* The [Table of Contents Extension] now supports new `permalink` option +* The Table of Contents Extension now supports new `permalink` option for creating [Sphinx]-style anchor links. -[Table of Contents Extension]: extensions/toc.html [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 +appending `markdown=1` to opening tag attributes. See Markdown Inside HTML +Blocks section for details. Thanks to [ryneeverett] for implementing this feature. -[Markdown Inside HTML Blocks]: extensions/extra.html#nested-markdown-inside-html-blocks [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]): +the Fenced Code Extension): ```.python hl_lines="1 3" # This line will be emphasized. @@ -69,7 +60,6 @@ the [Fenced Code Extension]): Thanks to [A. Jesse Jiryu Davis] for implementing this feature. -[Fenced Code Extension]: extensions/fenced_code_blocks.html [A. Jesse Jiryu Davis]: https://github.com/ajdavis * Various bug fixes have been made. See the diff --git a/docs/release-2.5.txt b/docs/change_log/release-2.5.md similarity index 87% rename from docs/release-2.5.txt rename to docs/change_log/release-2.5.md index 7cde02f4a..fe7a800c1 100644 --- a/docs/release-2.5.txt +++ b/docs/change_log/release-2.5.md @@ -1,8 +1,4 @@ title: Release Notes for v2.5 -prev_title: Release Notes for v2.6 -prev_url: release-2.6.html -next_title: Release Notes for v2.4 -next_url: release-2.4.html Python-Markdown 2.5 Release Notes ================================= @@ -20,14 +16,11 @@ Backwards-incompatible Changes [importlib]: https://pypi.python.org/pypi/importlib -* The `force_linenos` configuration key on the [CodeHilite Extension] has been **deprecated** +* 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`][linenums] keyword should be used + issuing a `DeprecationWarning`. The `linenums` keyword should be used instead, which provides more control of the output. -[CodeHilite Extension]: extensions/code_hilite.html -[linenums]: extensions/code_hilite.html#usage - * 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 @@ -96,25 +89,24 @@ Backwards-incompatible Changes $ python -m markdown -x markdown.extensions.extra input.txt - See the [documentation](reference.html#extensions) for a full explanation + 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.html#extension_configs) keyword should - be used instead. See the [documentation](reference.html#extension-configs) + [`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 +* 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. -[Smarty Extension]: extensions/smarty.html [Martin Altmayer]:https://github.com/MartinAltmayer * Named Extensions (strings passed to the [`extensions`][ex] keyword of @@ -146,7 +138,7 @@ What's New in Python-Markdown 2.5 the module. Extension authors will want to document carefully what is required to load their extensions. -[ex]: reference.html#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 @@ -159,8 +151,8 @@ What's New in Python-Markdown 2.5 code going forward. The included extensions provide a model for best practices. See the [API] documentation for a full explanation. -[ec]: reference.html#extension_configs -[API]: extensions/api.html#configsettings +[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 @@ -169,14 +161,12 @@ What's New in Python-Markdown 2.5 matches the format required by the `extension_configs` keyword. Note that [PyYAML] is required to parse YAML files. -[cli]: cli.html#using-extensions +[cli]: ../cli.md#using-extensions [YAML]: http://yaml.org/ [JSON]: http://json.org/ [PyYAML]: http://pyyaml.org/ -* The [admonition extension][ae] is no longer considered "experimental." - -[ae]: extensions/admonition.html +* 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 diff --git a/docs/release-2.6.txt b/docs/change_log/release-2.6.md similarity index 91% rename from docs/release-2.6.txt rename to docs/change_log/release-2.6.md index e4501628f..aeff75067 100644 --- a/docs/release-2.6.txt +++ b/docs/change_log/release-2.6.md @@ -1,8 +1,4 @@ title: Release Notes for v2.6 -prev_title: Change Log -prev_url: change_log.html -next_title: Release Notes for v2.5 -next_url: release-2.5.html Python-Markdown 2.6 Release Notes ================================= @@ -104,7 +100,7 @@ as follows (assuming the file `mdx_math.py` is installed at the root of your PYT Extension authors will want to update their documentation to reflect the new behavior. -See the [documentation](reference.html#extensions) for a full explanation +See the [documentation](../reference.md#extensions) for a full explanation of the current behavior. ### Extension Configuration as Part of Extension Name Deprecated @@ -112,16 +108,16 @@ of the current behavior. 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.html#extension_configs) keyword should -be used instead. See the [documentation](reference.html#extension-configs) +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][hid] Extension is pending deprecation and will raise a +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][TOC] Extension instead, which offers most of 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 @@ -129,8 +125,6 @@ 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`). -[hid]: extensions/header_id.html - ### The `configs` Keyword is Deprecated Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class @@ -178,8 +172,8 @@ options like so: 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.html#configsettings -[mext]: extensions/api.html#makeextension +[config]: ../extensions/api.md#configsettings +[mext]: ../extensions/api.md#makeextension What's New in Python-Markdown 2.6 --------------------------------- @@ -193,7 +187,7 @@ worked on PyPy for some time, it is now officially supported and tested on PyPy. ### YAML Style Meta-Data -The [Meta-Data] Extension now includes optional support for [YAML] style +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. @@ -204,13 +198,12 @@ party extension be used if you want true YAML support. See [Issue #390][#390] fo explanation. [MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata -[Meta-Data]: extensions/meta_data.html [YAML]: http://yaml.org/ [#390]: https://github.com/Python-Markdown/markdown/issues/390 ### Table of Contents Extension Refactored -The [Table of Contents][TOC] Extension has been refactored and some new features +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: @@ -234,11 +227,9 @@ listed below: 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. -[TOC]: extensions/toc.html - ### Pygments can now be disabled -The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`. +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 @@ -247,7 +238,6 @@ Pygments'. If a language is defined for a code block, it will be assigned to the (alternate output will not be entertained) and could potentially be used by a JavaScript library in the browser to highlight the code block. -[ch]: extensions/code_hilite.html [spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element ### Miscellaneous diff --git a/docs/cli.txt b/docs/cli.md similarity index 94% rename from docs/cli.txt rename to docs/cli.md index c2b37e4a9..b6889e135 100644 --- a/docs/cli.txt +++ b/docs/cli.md @@ -1,9 +1,4 @@ title: Command Line -prev_title: Library Reference -prev_url: reference.html -next_title: Extensions -next_url: extensions/index.html - Using Python-Markdown on the Command Line ========================================= @@ -15,7 +10,7 @@ Python-Markdown's various extensions. Generally, you will want to have the Markdown library fully installed on your system to run the command line script. See the -[Installation instructions](install.html) for details. +[Installation instructions](install.md) for details. Python-Markdown's command line script takes advantage of Python's `-m` flag. Therefore, assuming the python executable is on your system path, use the @@ -60,7 +55,7 @@ path. * __*nix__ (Linux, OSX, BSD, Unix, etc.): - As each *nix distribution is different and we can't possibly document all + As each \*nix distribution is different and we can't possibly document all of them here, we'll provide a few helpful pointers: * Some systems will automatically install the script on your path. Try it @@ -107,7 +102,7 @@ Using Extensions To load a Python-Markdown extension from the command line use the `-x` (or `--extension`) option. The extension module must be on your `PYTHONPATH` -(see the [Extension API](extensions/api.html) for details). The extension can +(see the [Extension API](extensions/api.md) for details). The extension can then be invoked by the name of that module using Python's dot syntax: $ python -m markdown -x path.to.module input.txt @@ -149,5 +144,5 @@ of your configuration file is automatically detected. [YAML]: http://yaml.org/ [JSON]: http://json.org/ [PyYAML]: http://pyyaml.org/ -[2.5 release notes]: release-2.5.txt +[2.5 release notes]: change_log/release-2.5.md diff --git a/docs/default.css b/docs/default.css deleted file mode 100644 index 7833719c1..000000000 --- a/docs/default.css +++ /dev/null @@ -1,261 +0,0 @@ -/* - * default.css_t - * ~~~~~~~~~~~~~ - * - * Sphinx stylesheet -- default theme. - * - * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - background-color: #1c4e63; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - -div.body { - background-color: #ffffff; - color: #000000; - padding: 0 20px 30px 20px; -} - -div.footer { - color: #ffffff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #ffffff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - line-height: 30px; - color: #ffffff; -} - -div.related a { - color: #ffffff; -} - -div.sphinxsidebar { -} - -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: #ffffff; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: #ffffff; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - color: #ffffff; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - - -/* for collapsible sidebar */ -div#sidebarbutton { - background-color: #3c6e83; -} - - -/* -- hyperlink styles ------------------------------------------------------ */ - -a { - color: #355f7c; - text-decoration: none; -} - -a:visited { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - - - -/* -- body styles ----------------------------------------------------------- */ - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: justify; - line-height: 130%; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.admonition p { - margin-bottom: 5px; -} - -div.admonition pre { - margin-bottom: 5px; -} - -div.admonition ul, div.admonition ol { - margin-bottom: 5px; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre { - padding: 5px; - background-color: #eeffcc; - color: #333333; - line-height: 120%; - border: 1px solid #ac9; - border-left: none; - border-right: none; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - -th { - background-color: #ede; -} - -.warning tt { - background: #efc2c2; -} - -.note tt { - background: #d6d6d6; -} - -.viewcode-back { - font-family: sans-serif; -} - -div.viewcode-block:target { - background-color: #f4debf; - border-top: 1px solid #ac9; - border-bottom: 1px solid #ac9; -} \ No newline at end of file diff --git a/docs/extensions/api.txt b/docs/extensions/api.md similarity index 99% rename from docs/extensions/api.txt rename to docs/extensions/api.md index 246bb27b0..8be2ab31a 100644 --- a/docs/extensions/api.txt +++ b/docs/extensions/api.md @@ -676,7 +676,7 @@ the module and call the `makeExtension` function to initiate your extension. [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 -[library reference]: ../reference.html +[Available Extensions]: index.md +[Footnotes]: https://github.com/Python-Markdown/mdx_footnotes +[Definition Lists]: https://github.com/Python-Markdown/mdx_definition_lists +[library reference]: ../reference.md diff --git a/docs/extensions/index.md b/docs/extensions/index.md new file mode 100644 index 000000000..2e735728b --- /dev/null +++ b/docs/extensions/index.md @@ -0,0 +1,85 @@ +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 to markdown with the `extensions` keyword. + + markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes']) + +See the [Library Reference](../reference.md#extensions) for more details. + +From the command line, specify an extension with the `-x` option. + + $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html + +See the [Command Line docs](../cli.md) or use the `--help` option for more details. + +!!! seealso "See Also" + If you would like to write your own extensions, see the + [Extension API](api.md) for details. + +Officially Supported Extensions +------------------------------- + +The extensions listed below are maintained and officially supported by +the Python-Markdown team. However, no extensions ship with Python-Markdown +by default. If you would like to use any of the extensions listed below, +you will need to install each of them individually. See the documentation +for each extension for specifics in instalation and usage. + +Extension | "Name" +------------------------------------ | --------------- +[Extra] | `extra` +    [Abbreviations][] | `abbr` +    [Attribute Lists][] | `attr_list` +    [Definition Lists][] | `def_list` +    [Fenced Code Blocks][] | `fenced_code` +    [Footnotes][] | `footnotes` +    [Tables][] | `tables` +    [Smart Strong][] | `smart_strong` +[Admonition][] | `admonition` +[CodeHilite][] | `codehilite` +[Meta-Data] | `meta` +[New Line to Break] | `nl2br` +[Sane Lists] | `sane_lists` +[SmartyPants] | `smarty` +[Table of Contents] | `toc` +[WikiLinks] | `wikilinks` + +[Extra]: https://github.com/Python-Markdown/mdx_extra +[Abbreviations]: https://github.com/Python-Markdown/mdx_abbreviations +[Attribute Lists]: https://github.com/Python-Markdown/mdx_attr_list +[Definition Lists]: https://github.com/Python-Markdown/mdx_definition_lists +[Fenced Code Blocks]: https://github.com/Python-Markdown/mdx_fenced_code_blocks +[Footnotes]: https://github.com/Python-Markdown/mdx_footnotes +[Tables]: https://github.com/Python-Markdown/mdx_tables +[Smart Strong]: https://github.com/Python-Markdown/mdx_smart_strong +[Admonition]: https://github.com/Python-Markdown/mdx_admonition +[CodeHilite]: https://github.com/Python-Markdown/mdx_code_hilite +[Meta-Data]: https://github.com/Python-Markdown/mdx_meta_data +[New Line to Break]: https://github.com/Python-Markdown/mdx_nl2br +[Sane Lists]: https://github.com/Python-Markdown/mdx_sane_lists +[SmartyPants]: https://github.com/Python-Markdown/mdx_smarty +[Table of Contents]: https://github.com/Python-Markdown/mdx_toc +[WikiLinks]: https://github.com/Python-Markdown/mdx_wikilinks + +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][list] +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. + +[list]: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt deleted file mode 100644 index ba9527467..000000000 --- a/docs/extensions/index.txt +++ /dev/null @@ -1,87 +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 to markdown with the `extensions` keyword. - - markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes']) - -See the [Library Reference](../reference.html#extensions) for more details. - -From the command line, specify an extension with the `-x` option. - - $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html - -See the [Command Line docs](../cli.html) or use the `--help` option for more details. - -!!! seealso "See Also" - If you would like to write your own extensions, see the - [Extension API](api.html) for details. - -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 using the "name" listed in the second column below. - -Extension | "Name" ------------------------------------- | --------------- -[Extra] | `markdown.extensions.extra` -    [Abbreviations][] | `markdown.extensions.abbr` -    [Attribute Lists][] | `markdown.extensions.attr_list` -    [Definition Lists][] | `markdown.extensions.def_list` -    [Fenced Code Blocks][] | `markdown.extensions.fenced_code` -    [Footnotes][] | `markdown.extensions.footnotes` -    [Tables][] | `markdown.extensions.tables` -    [Smart Strong][] | `markdown.extensions.smart_strong` -[Admonition][] | `markdown.extensions.admonition` -[CodeHilite][] | `markdown.extensions.codehilite` -[HeaderId] | `markdown.extensions.headerid` -[Meta-Data] | `markdown.extensions.meta` -[New Line to Break] | `markdown.extensions.nl2br` -[Sane Lists] | `markdown.extensions.sane_lists` -[SmartyPants] | `markdown.extensions.smarty` -[Table of Contents] | `markdown.extensions.toc` -[WikiLinks] | `markdown.extensions.wikilinks` - -[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 -[Admonition]: admonition.html -[CodeHilite]: code_hilite.html -[HeaderId]: header_id.html -[Meta-Data]: meta_data.html -[New Line to Break]: nl2br.html -[Sane Lists]: sane_lists.html -[SmartyPants]: smarty.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][list] -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. - -[list]: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..c9efc5844a2627a8474949724a2aefe4ab2baee4 GIT binary patch literal 15086 zcmcgz3tUxI_P$#EqsLfjrKaN}rF^8R7zl#$e#lE9E2sH4T54qp=Bv_FY)l=~00C>% zF&`;O=A+c|g@6JoRF;_+O)YUI9mCN{y9!+PeBZujUk}%FFE4Tbe#_&%_nf`g+Uv2` z`qsf@YGS&@bnm?;TsxRvy47UzG?`2tI@mscjPIA>yI#Gt&+aBu=mREG7uBIOT=7iM}d`t)*vk<+$7lLzev?;P$@UuUtE$9x=ZJ;KgrrPHgxHf;L zREU_9LdZFeV2(pVxNCgi_W%&(dJNPKbQg&7bOiZ=o_PKjA=Dgxg=ez*=AT>JE$`gg zj@jqdw%TE%=1U6R#J!xW!>URCi7O}gS(c9T5%?VW>Nz3wa|A&aZ}9Or_~`tNZ9ljt z%@^lQ!To*LPYXKo@tXl+#Y8_5*{AKZiKUl6=Nu!z$J3A{8nUQ4dg|tQDEGHK^6=Tr zP|K&&g2kFQ{6*@Eo>}-VCgJD*t{HRIY8mmbYjXsGkAC1o&7tjQ*tR)?#Ah?Z#3yeB ziPe(_inNzKw}$j?^JmNx1qugI{{bO;PQ4OPVzqFN9^j)BWWo2L+3!Y+FW!j|8|;YSI9)bXCj zMTsr5!o`LeAwuoNl0+Z*Jm(;3a|A`65F!9`cpkQv;rY%5sd2k<7sQGkb0fv(zlIC7 z7t1I3iNBBat~Lkm4d$CEk7yr=h1)ibJz&o9fo%5n-?)JS{IdOncdx59A zfM~N$N6vzn4cliADwBILJy>MIE|$IKYgzP?*FrqRXK&FzeBpMJNs|6c7ynOE_iI-& z)B)rVVtnFAV&JLYP`=DPLL@Ww2Kj)vZ^0mckT<9&s3V9z?*?iDYUtqF%|PzGzWi}| z@BH&ydKUd|?oxEM?2)1h(Z0Y^+B)yDxy9zwS$EC;Gy(TTf*3P8fw->?<>8LNqH~i2 zekd;+@I$5W{=QQ5{jO3xey~Dx`>H~?gNF|LD@5DEa`9k(xwtp?N}1b&ZEs;+?hE$< z8ma$?EwRjuK5iA^N39~rTq&IKFyVNmICZ5;Og&L4?%Pu?+!pR+9Pp7712LB;o%$GK1k=#{*n8zwFa#}{GU}q@i62>^?e`@{a_Cs-@+cWeNgt$dXHS6=UHv{pLR~4 zxd(JVs3oZRs9&mtBM(u~MVMv}dLDX$hpw7Uwkxnu{zpM=L5z)@kMnYV+N9nul#g}B z_gUdAv!(=^KYr7{ zEc1;3@e$5E+!LONGuIUl+=oE;h1`cjHeINF=*;*4-+ZW`T-={`rR?79%VxLK?aX(A zG#Ht@{nd5hm8CY={zf&mYII#nfx8u4%#HfgjE`)vC_ z9-3ueqHR!T?Qkw8ZJRwvY@HP$J_irX7kE}PXTa~#Twn2!0A0KcdrTEx;ev!xp4ZP6-feUiX)|H1k;IkV_JL#0SVlGsf8RVU=5t4DCG5 z)jo9F_Z!d0o`q@gy9yV^iM=U0JxCrLe3EeiKFPSS`t^Z=`R9k@ePvF+IKf-I|H`#| zm^`G6_ArO-J~A^FzB%ZaRfIU`qDS7@kFkEI{TV}(_ov4T2m7 zU8NpS8+`~pEJaPgoPN{lUT|&$K*{7H8R) z7B6TEdG9G(Fz`vn1zmjpXp*u8=m9*~^l*&_u0ITMQu2TtO6|jd!{w}5yMcHHnTpef zPCtyC@JYr6+5*-NYv}qaKL2uPr_67EI~R79fVKTW%=zj)WPFBC z>IZ9S+ga^AJ}*t|Pak9cD}AiK45;}0b77`r;qaDZgZQlFOuG0C8(fVwS%=zvtUf&K zPl*jGNEvLoEw;OA*+P<|uYdSu|7`ZnkE*Z91w0nNE*)cvNXR~}d zJ;;pwdH0&v2NEMqx=_Ie6Y^UhO*}lA4GvxDODi zX*kG^QxIXeaf5ZvZ6MZRtbsa#h*L18u|D+!1%g6AtWWrv-?Mh^4q~lB+=F)9AX~!o zbsglLm?~>HkH^*>oX|7(%-YBD|C86f=yJ&;g_ld*frH4LGT(B#^`1*5EpsoGwD{ue z)@JLDFS}#T`b0d(oXsCZnHdY+K%BR+hveNm+Z^Qk&2PEB-DuV|H!#?8f!Bzq7O9M z_?((I1oyV45{>gYwFn1SjU#P#K5?5+j#B z4a`Bwa5MNHiMm5C12NoqL+PtVH^>gC2<65L4C50RFu|F8h@=?Js_3{N z9Few2eJX1H;u+vvN(Nxitl@5y3|NQpljoRPPhB6xcdQF}zPZZZ{tv(N-X5TVAo>$+ zQjr%i)7r{_=a@4N);+K0sq2*(FERH=L6pNN|Gh1JO#klaM`j{lEhE;-I+nN!F$LBy zcrIeBhWn0&9$3RlTXN6?aRuVg(x-uMFfQqB=?P^^!2cMR^tMC{j(vhw=-DtXv1f8O zVyoMVLupu_Ia41HZA^boH(izx><+xRRMwxsD2d6eMcu(Vm^C2#tav73+^<43R0j4I zoXOA;XPl7?&2YxuvE|o1@DK~4ozceCaNCp=VkW*xY>)UNYiQPw#Ff~qX0I7HM-cax zGW^?yzZ>cS*baT#Q4hr92ja|?_@{#m-KhuUd-Q2T8IWgC2DddwKLj5^pw=L%gN;eS ziL5(`kFu9boS2vtu{qe1O$OKz`Bzx2Ga3G@Y{@_dVr9-`AfD|^hL*6U`)Ny%;SV`i zEDpI+(=D?i%*1hsF%#z|*1iEahLiy~g7gK{@rr*}GO!QfOong`?`xT?h`4k!WwI{QjX8R5iK85jdT=E}4E&+KGPK!qnYQ4oa8TmG#J{8r%8uX*(vA$y1>_VZ z@4z20#}H5?s4h88nD_Ec!=k=BpBar>x;`?r-)rNaJ*GXtQ6-+N^}6T_)ncmdTyT|N z@SQZ`%*%jvv-d)*nY|D8UsUgb{g>3yeNQKk?)%lG_^xxhPM-Tzl=(`rk|9{@2kHGm z*%JGNe7A-E@Nj|T-#b5<7^v2t(J*l%Ur=`BD!*Wk#2y~|SF(pj8PKrlLhH|X%?oSJ0-wxr46ZsWgqLFy1Qv26BM>f;Oc97&g_vIofimy&^f55AX{ z;Y5b{FZ9mq@z#4!>TStU55&i8da%jho_%I5Y_@A*>W~fWPf0t{`a^Z~1*2S>GO%yM zcLQZF6a7^7kM#Xar2}5aMm;(;^5FRo^ggX*(BorD2KOz;lEHt+{pmxdvB$?gBkkyB z`+|~zI`H{u%hP;^r8Y9SFW>Vb_-|R565W%1QuOE`1MCR>T4_fMw3upeE;NQOB#-uB zJPc(|Q!fKCzF^=k?6)gDcz!GUoW!}CflLR|;!C9rv?HzW&i4--&joolyT~u}xwfj= z>f#GvCE^)kOF9`8#;2FTtLS1b?(Gb^9b_s_kDtaqt+XQpU#M+0m}-Jms*MBb@w@8e3#w+*-mzk@%(3p2c4TlasFb4*>^P;)mLkj*rTupuW9>_v#Bk&e+WNxH;9s9#{K8q? z=_0>CeZZWCf5&y*xq2goDa89CD%UQ|cvk$ld#N~CkSTIgpOF|$ed+@3YZTTY9&XRa9M`>(pQQ|`LzdGQBz{rPTpN7_ z^FI=N*^^*C)2RFIO#Zz2(Zg~U#4gX7A6=aNZj>4Li^T}bLw})k{fuBU`XZY$r}!^i z{e~~!qhT)7AihN}g)47^^rcD-HTJtKU^)l}Cj9%FUUlongfilename.txt`. - This can be switched off if desired. See the - [Library Reference](reference.html#smart_emphasis) for details. + This can be disabled with an extension. * __Indentation/Tab Length__ @@ -91,7 +86,7 @@ are summarized below: be indented by at least four spaces (or one tab) for each level of nesting. In the event that one would prefer different behavior, - [tab_length](reference.html#tab_length) can be set to whatever length is + [tab_length](reference.md#tab_length) can be set to whatever length is desired. Be warned however, as this will affect indentation for all aspects of the syntax (including root level code blocks). @@ -101,7 +96,7 @@ are summarized below: the original) do not end one list and start a second list when the list marker (asterisks, pluses, hyphens, and numbers) changes. For consistency, Python-Markdown maintains the same behavior with no plans to change in the - foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.html) + foreseeable future. That said, the Sane List Extension is available to provide a less surprising behavior. diff --git a/docs/install.txt b/docs/install.md similarity index 88% rename from docs/install.txt rename to docs/install.md index c01c3b430..783b1b130 100644 --- a/docs/install.txt +++ b/docs/install.md @@ -1,8 +1,4 @@ title: Installation -prev_title: Summary -prev_url: index.html -next_title: Library Reference -next_url: reference.html Installing Python-Markdown ========================== @@ -19,7 +15,7 @@ or easy_install markdown -That's it! You're ready to [use](reference.html) Python-Markdown. Enjoy! +That's it! You're ready to [use](reference.md) Python-Markdown. Enjoy! Installing on Windows {: #windows } ----------------------------------- @@ -41,8 +37,8 @@ the Scripts directory is `C:\PythonXX\Scripts\` (were "XX" is the Python version number, i.e., "27"). Adjust the path according to your system and add to your system path. -Installing on *nix Systems {: #linux } --------------------------------------- +Installing on \*nix Systems {: #linux } +--------------------------------------- From the command line do the following (where 2.x is the version number): diff --git a/docs/reference.txt b/docs/reference.md similarity index 72% rename from docs/reference.txt rename to docs/reference.md index b65f2ddf4..424ba1a94 100644 --- a/docs/reference.txt +++ b/docs/reference.md @@ -23,24 +23,26 @@ The Details ----------- Python-Markdown provides two public functions ([`markdown.markdown`](#markdown) -and [`markdown.markdownFromFile`](#markdownFromFile)) both of which wrap the -public class [`markdown.Markdown`](#Markdown). If you're processing one +and [`markdown.markdownFromFile`](#markdownFromFile)) both of which wrap the +public class [`markdown.Markdown`](#Markdown). If you're processing one document at a time, these functions will serve your needs. However, if you need -to process multiple documents, it may be advantageous to create a single -instance of the `markdown.Markdown` class and pass multiple documents through +to process multiple documents, it may be advantageous to create a single +instance of the `markdown.Markdown` class and pass multiple documents through it. If you do use a single instance though, make sure to call the `reset` method appropriately ([see below](#convert)). -### `markdown.markdown (text [, **kwargs])` {: #markdown } +### markdown.markdown(text [, **kwargs]) {: #markdown } The following options are available on the `markdown.markdown` function: -* __`text`__{: #text } (required): The source Unicode string. +__text__{: #text } + +: The source Unicode string. (required) !!! note "Important" Python-Markdown expects **Unicode** as input (although some simple ASCII strings *may* work) and returns output as Unicode. - Do not pass encoded strings to it! If your input is encoded, (e.g. as + Do not pass encoded strings to it! If your input is encoded, (e.g. as UTF-8), it is your responsibility to decode it. For example: input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8") @@ -49,51 +51,53 @@ The following options are available on the `markdown.markdown` function: If you want to write the output to disk, you *must* encode it yourself: - output_file = codecs.open("some_file.html", "w", - encoding="utf-8", + output_file = codecs.open("some_file.html", "w", + encoding="utf-8", errors="xmlcharrefreplace" ) output_file.write(html) -* __`extensions`__{: #extensions }: A list of extensions. +__extensions__{: #extensions } + +: A list of extensions. - Python-Markdown provides an [API](extensions/api.html) for third parties to + Python-Markdown provides an [API](extensions/api.md) for third parties to write extensions to the parser adding their own additions or changes to the - syntax. A few commonly used extensions are shipped with the markdown - library. See the [extension documentation](extensions/index.html) for a + syntax. A few commonly used extensions are shipped with the markdown + library. See the [extension documentation](extensions/index.md) for a list of available extensions. - The list of extensions may contain instances of extensions and/or strings - of extension names. + The list of extensions may contain instances of extensions and/or strings + of extension names. extensions=[MyExtension(), 'path.to.my.ext'] - + !!! note The preferred method is to pass in an instance of an extension. Strings should only be used when it is impossible to import the Extension Class directly (from the command line or in a template). - + When passing in extension instances, each class instance must be a subclass - of `markdown.extensions.Extension` and any configuration options should be - defined when initiating the class instance rather than using the + of `markdown.extensions.Extension` and any configuration options should be + defined when initiating the class instance rather than using the [`extension_configs`](#extension_configs) keyword. For example: from markdown.extensions import Extension class MyExtension(Extension): # define your extension here... - + markdown.markdown(text, extensions=[MyExtension(option='value')]) - If an extension name is provided as a string, the extension must be - importable as a python module on your PYTHONPATH. Python's dot notation is - supported. Therefore, to import the 'extra' extension, one could do + If an extension name is provided as a string, the extension must be + importable as a python module on your PYTHONPATH. Python's dot notation is + supported. Therefore, to import the 'extra' extension, one could do `extensions=['markdown.extensions.extra']` - Additionally, a Class may be specified in the name. The class must be at the end of - the name and be separated by a colon from the module. + Additionally, a Class may be specified in the name. The class must be at the end of + the name 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: @@ -101,31 +105,32 @@ The following options are available on the `markdown.markdown` function: "path.to.module:SomeExtensionClass" !!! note - You should only need to specify the class name if more than one extension - is defined within the same module. The extensions that come with + You should only need to specify the class name if more than one extension + is defined within the same module. The extensions that come with Python-Markdown do *not* need to have the class name specified. However, doing so will not effect the behavior of the parser. When loading an extension by name (as a string), you may pass in - configuration settings to the extension using the + configuration settings to the extension using the [`extension_configs`](#extension_configs) keyword. !!! seealso "See Also" - See the documentation of the [Extension API](extensions/api.html) for + See the documentation of the [Extension API](extensions/api.md) for assistance in creating extensions. -* __`extension_configs`__{: #extension_configs }: A dictionary of - configuration settings for extensions. +__extension_configs__{: #extension_configs } + +: A dictionary of configuration settings for extensions. + + Any configuration settings will only be passed to extensions loaded by name + (as a string). When loading extensions as class instances, pass the + configuration settings directly to the class when initializing it. - Any configuration settings will only be passed to extensions loaded by name - (as a string). When loading extensions as class instances, pass the - configuration settings directly to the class when initializing it. - !!! Note The preferred method is to pass in an instance of an extension, which does not require use of the `extension_configs` keyword at all. See the [extensions](#extensions) keyword for details. - + The dictionary of configuration settings must be in the following format: extension_configs = { @@ -138,55 +143,53 @@ The following options are available on the `markdown.markdown` function: } } - See the documentation specific to the extension you are using for help in + See the documentation specific to the extension you are using for help in specifying configuration settings for that extension. -* __`output_format`__{: #output_format }: Format of output. +__output_format__{: #output_format }: + +: Format of output. Supported formats are: - * `"xhtml1"`: Outputs XHTML 1.x. **Default**. - * `"xhtml5"`: Outputs XHTML style tags of HTML 5 - * `"xhtml"`: Outputs latest supported version of XHTML (currently XHTML 1.1). - * `"html4"`: Outputs HTML 4 - * `"html5"`: Outputs HTML style tags of HTML 5 - * `"html"`: Outputs latest supported version of HTML (currently HTML 4). + * `"xhtml"`: Outputs XHTML style tags. **Default**. + * `"html"`: Outputs HTML style tags. The values can be in either lowercase or uppercase. !!! warning - It is suggested that the more specific formats (`"xhtml1"`, `"html5"`, & - `"html4"`) be used as the more general formats (`"xhtml"` or `"html"`) may - change in the future if it makes sense at that time. + It is suggested that the more specific formats (`"xhtml1"`, `"html5"`, & + `"html4"`) be used as the more general formats (`"xhtml"` or `"html"`) may + change in the future if it makes sense at that time. * __`safe_mode`__{: #safe_mode }: Disallow raw HTML. !!! warning "`safe_mode`" is deprecated and should not be used. - HTML sanitizers (like [Bleach]) provide a better solution for - dealing with markdown text submitted by untrusted users. + HTML sanitizers (like [Bleach]) provide a better solution for + dealing with markdown text submitted by untrusted users. import markdown import bleach html = bleach.clean(markdown.markdown(untrusted_text)) See the [release notes] for more info. - + [Bleach]: https://github.com/jsocol/bleach [release notes]: release-2.6.html - + The following values are accepted: * `False` (Default): Raw HTML is passed through unaltered. - * `replace`: Replace all HTML blocks with the text assigned to - `html_replacement_text` To maintain backward compatibility, setting + * `replace`: Replace all HTML blocks with the text assigned to + `html_replacement_text` To maintain backward compatibility, setting `safe_mode=True` will have the same effect as `safe_mode='replace'`. To replace raw HTML with something other than the default, do: - md = markdown.Markdown(safe_mode='replace', + md = markdown.Markdown(safe_mode='replace', html_replacement_text='--RAW HTML NOT ALLOWED--') * `remove`: All raw HTML will be completely stripped from the text with @@ -202,12 +205,12 @@ The following options are available on the `markdown.markdown` function:

Foo <b>bar</b>.

- !!! Note - "safe_mode" also alters the default value for the + !!! Note + "safe_mode" also alters the default value for the [`enable_attributes`](#enable_attributes) option. - -* __`html_replacement_text`__{: #html_replacement_text }: Text used when + +* __`html_replacement_text`__{: #html_replacement_text }: Text used when safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`. !!! warning @@ -216,20 +219,20 @@ The following options are available on the `markdown.markdown` function: * __`tab_length`__{: #tab_length }: Length of tabs in the source. Default: 4 -* __`enable_attributes`__{: #enable_attributes}: Enable the conversion of - attributes. Defaults to `True`, unless [`safe_mode`](#safe_mode) is enabled, +* __`enable_attributes`__{: #enable_attributes}: Enable the conversion of + attributes. Defaults to `True`, unless [`safe_mode`](#safe_mode) is enabled, in which case the default is `False`. - !!! Note - `safe_mode` only overrides the default. If `enable_attributes` + !!! Note + `safe_mode` only overrides the default. If `enable_attributes` is explicitly set, the explicit value is used regardless of `safe_mode`. However, this could potentially allow an untrusted user to inject JavaScript into your documents. -* __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_` +* __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_` intelligently Default: True -* __`lazy_ol`__{: #lazy_ol }: Ignore number of first item of ordered lists. +* __`lazy_ol`__{: #lazy_ol }: Ignore number of first item of ordered lists. Default: True Given the following list: @@ -238,7 +241,7 @@ The following options are available on the `markdown.markdown` function: 5. Oranges 6. Pears - By default markdown will ignore the fact the the first line started + By default markdown will ignore the fact the the first line started with item number "4" and the HTML list will start with a number "1". If `lazy_ol` is set to `False`, then markdown will output the following HTML: @@ -249,14 +252,17 @@ The following options are available on the `markdown.markdown` function:
  • Pears
    • +: Length of tabs in the source. Default: 4 ### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile } -With a few exceptions, `markdown.markdownFromFile` accepts the same options as -`markdown.markdown`. It does **not** accept a `text` (or Unicode) string. +With a few exceptions, `markdown.markdownFromFile` accepts the same options as +`markdown.markdown`. It does **not** accept a `text` (or Unicode) string. Instead, it accepts the following required options: -* __`input`__{: #input } (required): The source text file. +__input__{: #input } (required) + +: The source text file. `input` may be set to one of three options: @@ -264,7 +270,9 @@ Instead, it accepts the following required options: * a readable file-like object, * or `None` (default) which will read from `stdin`. -* __`output`__{: #output }: The target which output is written to. +__output__{: #output } + +: The target which output is written to. `output` may be set to one of three options: @@ -272,54 +280,57 @@ Instead, it accepts the following required options: * a writable file-like object, * or `None` (default) which will write to `stdout`. -* __`encoding`__{: #encoding }: The encoding of the source text file. Defaults - to `"utf-8"`. The same encoding will always be used for input and output. - The `xmlcharrefreplace` error handler is used when encoding the output. +__encoding__{: #encoding } - !!! Note +: The encoding of the source text file. + + Defaults to `"utf-8"`. The same encoding will always be used for input and output. + The `xmlcharrefreplace` error handler is used when encoding the output. + + !!! Note This is the only place that decoding and encoding of Unicode takes place in Python-Markdown. If this rather naive solution does not meet your specific needs, it is suggested that you write your own code to handle your encoding/decoding needs. -### `markdown.Markdown ([**kwargs])` {: #Markdown } +### markdown.Markdown([**kwargs]) {: #Markdown } The same options are available when initializing the `markdown.Markdown` class as on the [`markdown.markdown`](#markdown) function, except that the class does **not** accept a source text string on initialization. Rather, the source text string must be passed to one of two instance methods: -* `Markdown.convert(source)`{: #convert } +#### Markdown.convert(source) {: #convert } + +The `source` text must meet the same requirements as the [`text`](#text) +argument of the [`markdown.markdown`](#markdown) function. + +You should also use this method if you want to process multiple strings +without creating a new instance of the class for each string. - The `source` text must meet the same requirements as the [`text`](#text) - argument of the [`markdown.markdown`](#markdown) function. + md = markdown.Markdown() + html1 = md.convert(text1) + html2 = md.convert(text2) - You should also use this method if you want to process multiple strings - without creating a new instance of the class for each string. +Depending on which options and/or extensions are being used, the parser may +need its state reset between each call to `convert`, otherwise performance +can degrade drastically: - md = markdown.Markdown() - html1 = md.convert(text1) - html2 = md.convert(text2) + html1 = md.convert(text1) + md.reset() + html2 = md.convert(text2) - Depending on which options and/or extensions are being used, the parser may - need its state reset between each call to `convert`, otherwise performance - can degrade drastically: +To make this easier, you can also chain calls to `reset` together: - html1 = md.convert(text1) - md.reset() - html2 = md.convert(text2) - - To make this easier, you can also chain calls to `reset` together: - - html3 = md.reset().convert(text3) + html3 = md.reset().convert(text3) -* `Markdown.convertFile(**kwargs)`{: #convertFile } +#### Markdown.convertFile(**kwargs) {: #convertFile } - The arguments of this method are identical to the arguments of the same - name on the `markdown.markdownFromFile` function ([`input`](#input), - [`output`](#output), and [`encoding`](#encoding)). As with the - [`convert`](#convert) method, this method should be used to - process multiple files without creating a new instance of the class for - each document. State may need to be `reset` between each call to - `convertFile` as is the case with `convert`. +The arguments of this method are identical to the arguments of the same +name on the `markdown.markdownFromFile` function ([`input`](#input), +[`output`](#output), and [`encoding`](#encoding)). As with the +[`convert`](#convert) method, this method should be used to +process multiple files without creating a new instance of the class for +each document. State may need to be `reset` between each call to +`convertFile` as is the case with `convert`. diff --git a/docs/release-2.0.1.txt b/docs/release-2.0.1.txt deleted file mode 100644 index c0b890a91..000000000 --- a/docs/release-2.0.1.txt +++ /dev/null @@ -1,22 +0,0 @@ -title: Release Notes for v2.0.1 -prev_title: Release Notes for v2.0.2 -prev_url: release-2.0.2.html -next_title: Release Notes for v2.0 -next_url: release-2.0.html - -Python-Markdown 2.0.1 Release Notes -=================================== - -Python-Markdown 2.0.1 is a bug-fix release. No new features have been added. -Most notably, various issues with the command line script have been fixed. -There have also been a few fixes for minor parsing bugs in some edge cases. -For a full list of changes, see the git log. - -Backwards-incompatible Changes ------------------------------- - -Due to various complications in how Python handles command line scripts in -difference systems and with different installation tools, we were forced to -rename the command line script to `markdown` (no `.py`). A matching batch -script will get installed on Windows. Any shell scripts which call -`markdown.py` will need to be altered to call `markdown` instead. diff --git a/docs/release-2.0.2.txt b/docs/release-2.0.2.txt deleted file mode 100644 index 5315c8009..000000000 --- a/docs/release-2.0.2.txt +++ /dev/null @@ -1,15 +0,0 @@ -title: Release Notes for v2.0.2 -prev_title: Release Notes for v2.1.0 -prev_url: release-2.1.0.html -next_title: Release Notes for v2.0.1 -next_url: release-2.0.1.html - -Python-Markdown 2.0.2 Release Notes -=================================== - -Python-Markdown 2.0.2 is a bug-fix release. No new features have been added. -Most notably, the setup script has been updated to include a dependency on -ElementTree on older versions of Python (< 2.5). There have also been a few -fixes for minor parsing bugs in some edge cases. For a full list of changes, -see the git log. - diff --git a/docs/release-2.1.1.txt b/docs/release-2.1.1.txt deleted file mode 100644 index 59caf6842..000000000 --- a/docs/release-2.1.1.txt +++ /dev/null @@ -1,13 +0,0 @@ -title: Release Notes for v2.1.1 -prev_title: Release Notes for v2.2.0 -prev_url: release-2.2.0.html -next_title: Release Notes for v2.1.0 -next_url: release-2.1.0.html - -Python-Markdown 2.1.1 Release Notes -=================================== - -Python-Markdown 2.1.1 is a bug-fix release. No new features have been added. -Most notably, a bug which caused raw HTML paring to run __very__ slowly has -been fixed along with a few bugs which caused the parser to raise exceptions -while parsing. For a full list of changes, see the git log. diff --git a/docs/release-2.2.1.txt b/docs/release-2.2.1.txt deleted file mode 100644 index fe27c71f9..000000000 --- a/docs/release-2.2.1.txt +++ /dev/null @@ -1,12 +0,0 @@ -title: Release Notes for v2.2.1 -prev_title: Release Notes for v2.3 -prev_url: release-2.3.html -next_title: Release Notes for v2.2.0 -next_url: release-2.2.0.html - -Python-Markdown 2.2.1 Release Notes -=================================== - -Python-Markdown 2.2.1 is a bug-fix release. No new features have been added. -However, at least one bug fix does not work in Python 2.4 so that version of -Python is no longer supported. For a full list of changes, see the git log. diff --git a/docs/siteindex.txt b/docs/siteindex.md similarity index 100% rename from docs/siteindex.txt rename to docs/siteindex.md diff --git a/docs/test_suite.txt b/docs/test_suite.md similarity index 100% rename from docs/test_suite.txt rename to docs/test_suite.md diff --git a/makefile b/makefile index 2752d6a05..7a78213b8 100644 --- a/makefile +++ b/makefile @@ -35,8 +35,8 @@ build-win: .PHONY : docs docs: - python setup.py build_docs --force - cd build/docs && zip -r ../docs.zip . + mkdocs build --clean + cd site && zip -r ../docs.zip . .PHONY : test test: diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..510524a19 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,39 @@ +site_name: Python-Markdown +site_url: https://Python-Markdown.github.io +repo_url: https://github.com/Python-Markdown/markdown +site_author: "The Python-Markdown Project" +copyright: "Copyright © 2010-2017" + +use_directory_urls: true + +theme: + name: nature + icon: py.png + release: 2.6.9 + issue_tracker: https://github.com/Python-Markdown/markdown/issues + +pages: + - Python-Markdown: index.md + - Installation: install.md + - Library Reference: reference.md + - Command Line: cli.md + - Extensions: extensions/index.md + - Extension API: extensions/api.md + - Test Suite: test_suite.md + - Change Log: change_log/index.md + - Release Notes for v.2.6: change_log/release-2.6.md + - Release Notes for v.2.5: change_log/release-2.5.md + - Release Notes for v.2.4: change_log/release-2.4.md + - Release Notes for v.2.3: change_log/release-2.3.md + - Release Notes for v.2.2: change_log/release-2.2.md + - Release Notes for v.2.1: change_log/release-2.1.md + - Release Notes for v.2.0: change_log/release-2.0.md + - Authors: authors.md + +markdown_extensions: + - extra + - admonition + - smarty + - codehilite + - toc: + permalink: true diff --git a/setup.py b/setup.py index 3821c6c24..51b092aa9 100755 --- a/setup.py +++ b/setup.py @@ -5,10 +5,6 @@ import os from distutils.core import setup from distutils.command.install_scripts import install_scripts -from distutils.command.build import build -from distutils.core import Command -from distutils.util import change_root, newer -import codecs import imp @@ -68,150 +64,6 @@ def run(self): print('ERROR: Unable to create %s: %s' % (bat_path, err)) -class build_docs(Command): - - """ Build markdown documentation into html.""" - - description = '"build" documentation (convert markdown text to html)' - - user_options = [ - ('build-base=', 'd', 'directory to "build" to'), - ('force', 'f', 'forcibly build everything (ignore file timestamps)'), - ] - - boolean_options = ['force'] - - def initialize_options(self): - self.build_base = None - self.force = None - self.docs = None - self.sitemap = '' - - def finalize_options(self): - self.set_undefined_options( - 'build', - ('build_base', 'build_base'), - ('force', 'force') - ) - self.docs = self._get_docs() - - def _get_docs(self): - for root, dirs, files in os.walk('docs'): - for file in files: - if not file.startswith('_'): - path = os.path.join(root, file) - yield path - - def _get_context(self, src, path): - """ Build and return context to pass to template. """ - # set defaults - c = { - 'title': '', - 'prev_url': '', - 'prev_title': '', - 'next_url': '', - 'next_title': '', - 'crumb': '', - 'version': version, - } - c['body'] = self.md.convert(src) - c['toc'] = self.md.toc - for k, v in self.md.Meta.items(): - c[k] = ' '.join(v) - self.md.reset() - # Manipulate path - path = path[len(os.path.join(self.build_base, 'docs/')):] - dir, file = os.path.split(path) - name, ext = os.path.splitext(file) - parts = [x for x in dir.split(os.sep) if x] - c['source'] = '%s.txt' % name - c['base'] = '../' * len(parts) - # Build page title - if name.lower() != 'index' or parts: - c['page_title'] = '%s — Python Markdown' % c['title'] - else: - c['page_title'] = 'Python Markdown' - # Build crumb trail - crumbs = [] - ctemp = '
  • %s »
    • ' - for n, part in enumerate(parts): - href = ('../' * n) + 'index.html' - label = part.replace('_', ' ').capitalize() - crumbs.append(ctemp % (href, label)) - if c['title'] and name.lower() != 'index': - crumbs.append(ctemp % (file, c['title'])) - c['crumb'] = '\n'.join(crumbs) - return c - - def run(self): - # Before importing markdown, tweak sys.path to import from the - # build directory (2to3 might have run on the library). - bld_cmd = self.get_finalized_command("build") - sys.path.insert(0, bld_cmd.build_lib) - try: - import markdown - except ImportError: - print('skipping build_docs: Markdown "import" failed!') - else: - with codecs.open('docs/_template.html', encoding='utf-8') as f: - template = f.read() - self.md = markdown.Markdown( - extensions=[ - 'extra', - 'toc(permalink=true)', - 'meta', - 'admonition', - 'smarty' - ] - ) - for infile in self.docs: - outfile, ext = os.path.splitext(infile) - if ext == '.txt': - # Copy src to .txt file - srcfile = outfile + '.txt' - srcfile = change_root(self.build_base, srcfile) - self.mkpath(os.path.split(srcfile)[0]) - self.copy_file(infile, srcfile) - # Render html file - outfile += '.html' - outfile = change_root(self.build_base, outfile) - self.mkpath(os.path.split(outfile)[0]) - if self.force or newer(infile, outfile): - if self.verbose: - print('Converting %s -> %s' % (infile, outfile)) - if not self.dry_run: - with codecs.open(infile, encoding='utf-8') as f: - src = f.read() - out = template % self._get_context(src, outfile) - doc = open(outfile, 'wb') - doc.write(out.encode('utf-8')) - doc.close() - else: - outfile = change_root(self.build_base, infile) - self.mkpath(os.path.split(outfile)[0]) - self.copy_file(infile, outfile) - - -class md_build(build): - - """ Run "build_docs" command from "build" command. """ - - user_options = build.user_options + [ - ('no-build-docs', None, 'do not build documentation'), - ] - - boolean_options = build.boolean_options + ['build-docs'] - - def initialize_options(self): - build.initialize_options(self) - self.no_build_docs = False - - def has_docs(self): - return not self.no_build_docs - - sub_commands = build.sub_commands + [('build_docs', has_docs)] - - long_description = ''' This is a Python implementation of John Gruber's Markdown_. It is almost completely compliant with the reference implementation, @@ -220,8 +72,8 @@ def has_docs(self): supported by the `Available Extensions`_. .. _Markdown: http://daringfireball.net/projects/markdown/ -.. _Features: https://pythonhosted.org/Markdown/index.html#Features -.. _`Available Extensions`: https://pythonhosted.org/Markdown/extensions/index.html +.. _Features: https://pythonhosted.org/Markdown/#Features +.. _`Available Extensions`: https://pythonhosted.org/Markdown/extensions/ Support ======= @@ -248,9 +100,7 @@ def has_docs(self): packages=['markdown', 'markdown.extensions'], scripts=['bin/%s' % SCRIPT_NAME], cmdclass={ - 'install_scripts': md_install_scripts, - 'build_docs': build_docs, - 'build': md_build + 'install_scripts': md_install_scripts }, classifiers=[ 'Development Status :: %s' % DEVSTATUS, diff --git a/test-requirements.txt b/test-requirements.txt index b7bcf16d1..65bfae034 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -2,4 +2,5 @@ nose coverage<4.0 pyyaml pytidylib -pygments +mkdocs +mkdocs-nature From 3d1c70c597c5426de771495f1240b7555744b414 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 6 Dec 2017 15:18:20 -0500 Subject: [PATCH 2/7] Converted extension docs to mkdocs. --- .gitignore | 1 + .../{abbreviations.txt => abbreviations.md} | 8 +- .../{admonition.txt => admonition.md} | 6 +- docs/extensions/api.md | 4 - .../{attr_list.txt => attr_list.md} | 10 +-- .../{code_hilite.txt => code_hilite.md} | 10 +-- ...finition_lists.txt => definition_lists.md} | 10 +-- docs/extensions/{extra.txt => extra.md} | 24 +++--- ..._code_blocks.txt => fenced_code_blocks.md} | 10 +-- .../{footnotes.txt => footnotes.md} | 12 +-- .../{header_id.txt => header_id.md} | 18 ++--- docs/extensions/index.md | 7 +- .../{meta_data.txt => meta_data.md} | 14 ++-- docs/extensions/{nl2br.txt => nl2br.md} | 10 +-- .../{sane_lists.txt => sane_lists.md} | 10 +-- .../{smart_strong.txt => smart_strong.md} | 10 +-- docs/extensions/{smarty.txt => smarty.md} | 8 +- docs/extensions/{tables.txt => tables.md} | 10 +-- docs/extensions/{toc.txt => toc.md} | 12 +-- .../{wikilinks.txt => wikilinks.md} | 14 ++-- docs/siteindex.md | 78 ------------------- mkdocs.yml | 18 +++++ 22 files changed, 84 insertions(+), 220 deletions(-) rename docs/extensions/{abbreviations.txt => abbreviations.md} (79%) rename docs/extensions/{admonition.txt => admonition.md} (91%) rename docs/extensions/{attr_list.txt => attr_list.md} (87%) rename docs/extensions/{code_hilite.txt => code_hilite.md} (95%) rename docs/extensions/{definition_lists.txt => definition_lists.md} (75%) rename docs/extensions/{extra.txt => extra.md} (88%) rename docs/extensions/{fenced_code_blocks.txt => fenced_code_blocks.md} (90%) rename docs/extensions/{footnotes.txt => footnotes.md} (87%) rename docs/extensions/{header_id.txt => header_id.md} (85%) rename docs/extensions/{meta_data.txt => meta_data.md} (91%) rename docs/extensions/{nl2br.txt => nl2br.md} (67%) rename docs/extensions/{sane_lists.txt => sane_lists.md} (83%) rename docs/extensions/{smart_strong.txt => smart_strong.md} (78%) rename docs/extensions/{smarty.txt => smarty.md} (91%) rename docs/extensions/{tables.txt => tables.md} (78%) rename docs/extensions/{toc.txt => toc.md} (91%) rename docs/extensions/{wikilinks.txt => wikilinks.md} (88%) delete mode 100644 docs/siteindex.md diff --git a/.gitignore b/.gitignore index 6ac9fff47..96c6778e3 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ test-output.html build/* dist/* tmp/* +site/* MANIFEST .venv *~ diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.md similarity index 79% rename from docs/extensions/abbreviations.txt rename to docs/extensions/abbreviations.md index 9ac7c9534..c5e19dfc5 100644 --- a/docs/extensions/abbreviations.txt +++ b/docs/extensions/abbreviations.md @@ -1,8 +1,4 @@ -title: Abbreviations Extension -prev_title: Extra Extension -prev_url: extra.html -next_title: Attribute Lists Extension -next_url: attr_list.html +title: Abbreviations Extension Abbreviations ============= @@ -39,7 +35,7 @@ will be rendered as: Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.abbr` +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.abbr` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.md similarity index 91% rename from docs/extensions/admonition.txt rename to docs/extensions/admonition.md index d68bd5de1..1775bd206 100644 --- a/docs/extensions/admonition.txt +++ b/docs/extensions/admonition.md @@ -1,8 +1,4 @@ -title: Admonition Extension -prev_title: Smart Strong Extension -prev_url: smart_strong.html -next_title: CodeHilite Extension -next_url: code_hilite.html +title: Admonition Extension Admonition ========== diff --git a/docs/extensions/api.md b/docs/extensions/api.md index 8be2ab31a..1caa5c9b1 100644 --- a/docs/extensions/api.md +++ b/docs/extensions/api.md @@ -1,8 +1,4 @@ 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 ====================================== diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.md similarity index 87% rename from docs/extensions/attr_list.txt rename to docs/extensions/attr_list.md index 195134731..e57572655 100644 --- a/docs/extensions/attr_list.txt +++ b/docs/extensions/attr_list.md @@ -1,8 +1,4 @@ -title: Attribute Lists Extension -prev_title: Abbreviations Extension -prev_url: abbreviations.html -next_title: Definition Lists Extension -next_url: definition_lists.html +title: Attribute Lists Extension Attribute Lists =============== @@ -82,7 +78,7 @@ The above results in the following output: Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.attr_list` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.attr_list` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.md similarity index 95% rename from docs/extensions/code_hilite.txt rename to docs/extensions/code_hilite.md index c2980f297..0389caffc 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.md @@ -1,8 +1,4 @@ -title: CodeHilite Extension -prev_title: Admonition Extension -prev_url: admonition.html -next_title: HeaderId Extension -next_url: header_id.html +title: CodeHilite Extension CodeHilite ========== @@ -162,10 +158,10 @@ Lets see the source for that: Usage ----- -See [Extensions](index.html) for general extension usage, specify +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.codehilite` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.md similarity index 75% rename from docs/extensions/definition_lists.txt rename to docs/extensions/definition_lists.md index d7003e29a..7f72448ca 100644 --- a/docs/extensions/definition_lists.txt +++ b/docs/extensions/definition_lists.md @@ -1,8 +1,4 @@ -title: Definition Lists Extension -prev_title: Attribute Lists Extension -prev_url: attr_list.html -next_title: Fenced Code Blocks Extension -next_url: fenced_code_blocks.html +title: Definition Lists Extension Definition Lists ================ @@ -47,7 +43,7 @@ will be rendered as: Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.def_list` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.def_list` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.md similarity index 88% rename from docs/extensions/extra.txt rename to docs/extensions/extra.md index 5347d81d1..1f33ba621 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.md @@ -1,8 +1,4 @@ -title: Extra Extension -prev_title: Extensions -prev_url: index.html -next_title: Abbreviations Extension -next_url: abbreviations.html +title: Extra Extension Python-Markdown Extra ===================== @@ -15,13 +11,13 @@ A compilation of various Python-Markdown extensions that (mostly) imitates 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) +* [Abbreviations](abbreviations.md) +* [Attribute Lists](attr_list.md) +* [Definition Lists](definition_lists.md) +* [Fenced Code Blocks](fenced_code_blocks.md) +* [Footnotes](footnotes.md) +* [Tables](tables.md) +* [Smart Strong](smart_strong.md) See each individual extension for syntax documentation. Extra and all its supported extensions are included in the standard Markdown library. @@ -34,13 +30,13 @@ From the Python interpreter: >>> import markdown >>> html = markdown.markdown(text, ['markdown.extensions.extra']) -There may be [additional extensions](index.html) that are distributed with +There may be [additional extensions](index.md) 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)). +(see the [Extension API](api.md)). Markdown Inside HTML Blocks --------------------------- diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.md similarity index 90% rename from docs/extensions/fenced_code_blocks.txt rename to docs/extensions/fenced_code_blocks.md index 982f5d4f3..7bfffa890 100644 --- a/docs/extensions/fenced_code_blocks.txt +++ b/docs/extensions/fenced_code_blocks.md @@ -1,8 +1,4 @@ -title: Fenced Code Blocks Extension -prev_title: Definition Lists Extension -prev_url: definition_lists.html -next_title: Footnotes Extension -next_url: footnotes.html +title: Fenced Code Blocks Extension Fenced Code Blocks ================== @@ -106,7 +102,7 @@ The lines can be specified with PHP Extra's syntax: Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.fenced_code` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.fenced_code` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.md similarity index 87% rename from docs/extensions/footnotes.txt rename to docs/extensions/footnotes.md index e9b0451f8..2554bbd64 100644 --- a/docs/extensions/footnotes.txt +++ b/docs/extensions/footnotes.md @@ -1,8 +1,4 @@ -title: Footnotes Extension -prev_title: Fenced Code Blocks Extension -prev_url: fenced_code_blocks.html -next_title: Tables Extension -next_url: tables.html +title: Footnotes Extension Footnotes ========= @@ -64,10 +60,10 @@ is indented consistently and any errors are more easily discernible by the autho Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.footnotes` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.footnotes` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.md similarity index 85% rename from docs/extensions/header_id.txt rename to docs/extensions/header_id.md index 5557b1b0f..9aadf76be 100644 --- a/docs/extensions/header_id.txt +++ b/docs/extensions/header_id.md @@ -1,8 +1,4 @@ -title: HeaderId Extension -prev_title: CodeHilite Extension -prev_url: code_hilite.html -next_title: Meta-Data Extension -next_url: meta_data.html +title: HeaderId Extension HeaderId ======== @@ -20,7 +16,7 @@ This extension is included in the standard Markdown library. Extension should be used instead, which offers most the features of this extension and more. -[toc]: toc.html +[toc]: toc.md Syntax ------ @@ -42,10 +38,10 @@ Results in: Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.headerid` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.headerid` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: @@ -74,7 +70,7 @@ The following options are provided to configure the output: The `forceid` setting turns on or off the automatically generated ids for headers that do not have one explicitly defined (using the - [Attribute List](attr_list.html) extension). + [Attribute List](attr_list.md) extension). >>> text = ''' ... # Some Header @@ -103,7 +99,7 @@ The following options are provided to configure the output: Using with Meta-Data -------------------- -The HeaderId extension also supports the [Meta-Data](meta_data.html) extension. +The HeaderId extension also supports the [Meta-Data](meta_data.md) extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are: diff --git a/docs/extensions/index.md b/docs/extensions/index.md index 2e735728b..23c4133b7 100644 --- a/docs/extensions/index.md +++ b/docs/extensions/index.md @@ -1,9 +1,4 @@ -title: Extensions -prev_title: Command Line -prev_url: ../cli.html -next_title: Extra Extension -next_url: extra.html - +title: Extensions Available Extensions ==================== diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.md similarity index 91% rename from docs/extensions/meta_data.txt rename to docs/extensions/meta_data.md index 4a4fe62ac..b87a7751b 100644 --- a/docs/extensions/meta_data.txt +++ b/docs/extensions/meta_data.md @@ -1,8 +1,4 @@ -title: Meta-Data Extension -prev_title: HeaderId Extension -prev_url: header_id.html -next_title: New Line to Break Extension -next_url: nl2br.html +title: Meta-Data Extension Meta-Data ========= @@ -59,8 +55,8 @@ by Markdown. Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.meta` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.meta` as the name of the extension. Accessing the Meta-Data ----------------------- @@ -101,10 +97,10 @@ Compatible Extensions The following extensions are currently known to work with the Meta-Data extension. The keywords they are known to support are also listed. -* [HeaderId](header_id.html) +* [HeaderId](header_id.md) * `header_level` * `header_forceid` -* [WikiLinks](wikilinks.html) +* [WikiLinks](wikilinks.md) * `wiki_base_url` * `wiki_end_url` * `wiki_html_class` diff --git a/docs/extensions/nl2br.txt b/docs/extensions/nl2br.md similarity index 67% rename from docs/extensions/nl2br.txt rename to docs/extensions/nl2br.md index 8ba27c8f9..da419523e 100644 --- a/docs/extensions/nl2br.txt +++ b/docs/extensions/nl2br.md @@ -1,8 +1,4 @@ -title: New Line to Break Extension -prev_title: Meta-Data Extension -prev_url: meta_data.html -next_title: Sane Lists Extension -next_url: sane_lists.html +title: New Line to Break Extension New-Line-to-Break Extension =========================== @@ -31,7 +27,7 @@ Example Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.nl2br` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.nl2br` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/sane_lists.txt b/docs/extensions/sane_lists.md similarity index 83% rename from docs/extensions/sane_lists.txt rename to docs/extensions/sane_lists.md index 8f713d0a7..e1a9bab83 100644 --- a/docs/extensions/sane_lists.txt +++ b/docs/extensions/sane_lists.md @@ -1,8 +1,4 @@ -title: Sane Lists Extension -prev_title: New Line to Break Extension -prev_url: nl2br.html -next_title: SmartyPants Extension -next_url: smarty.html +title: Sane Lists Extension Sane Lists ========== @@ -67,7 +63,7 @@ In all other ways, Sane Lists should behave as normal Markdown lists. Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.sane_lists` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.sane_lists` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.md similarity index 78% rename from docs/extensions/smart_strong.txt rename to docs/extensions/smart_strong.md index e2e545883..29bd0c941 100644 --- a/docs/extensions/smart_strong.txt +++ b/docs/extensions/smart_strong.md @@ -1,8 +1,4 @@ -title: Smart Strong Extension -prev_title: Tables Extension -prev_url: tables.html -next_title: Admonition Extension -next_url: admonition.html +title: Smart Strong Extension Smart_Strong ============ @@ -35,7 +31,7 @@ Example Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.smart_strong` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.smart_strong` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/smarty.txt b/docs/extensions/smarty.md similarity index 91% rename from docs/extensions/smarty.txt rename to docs/extensions/smarty.md index 247658ab2..e09aa6e17 100644 --- a/docs/extensions/smarty.txt +++ b/docs/extensions/smarty.md @@ -1,8 +1,4 @@ title: SmartyPants Extension -prev_title: Sane Lists Extension -prev_url: sane_lists.html -next_title: Table of Contents Extension -next_url: toc.html SmartyPants =========== @@ -55,10 +51,10 @@ the German language: Usage ----- -See [Extensions](index.html) for general extension usage, specify +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.smarty` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: diff --git a/docs/extensions/tables.txt b/docs/extensions/tables.md similarity index 78% rename from docs/extensions/tables.txt rename to docs/extensions/tables.md index 759772a02..7ae10e844 100644 --- a/docs/extensions/tables.txt +++ b/docs/extensions/tables.md @@ -1,8 +1,4 @@ -title: Tables Extension -prev_title: Footnotes Extension -prev_url: footnotes.html -next_title: Smart Strong Extension -next_url: smart_strong.html +title: Tables Extension Tables ====== @@ -52,7 +48,7 @@ will be rendered as: Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.tables` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.tables` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.md similarity index 91% rename from docs/extensions/toc.txt rename to docs/extensions/toc.md index 2cd1fa15f..5b356090f 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.md @@ -1,8 +1,4 @@ -title: Table of Contents Extension -prev_title: SmartyPants Extension -prev_url: smarty.html -next_title: WikiLinks Extension -next_url: wikilinks.html +title: Table of Contents Extension Table of Contents ================= @@ -66,10 +62,10 @@ one to insert the Table of Contents elsewhere in their page template. For exampl Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.toc` +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.toc` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: @@ -124,4 +120,4 @@ The following options are provided to configure the output: The callable must return a string appropriate for use in HTML `id` attributes. * **`separator`**: - Word separator. Character which replaces white space in id. Defaults to "`-`". \ No newline at end of file + Word separator. Character which replaces white space in id. Defaults to "`-`". diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.md similarity index 88% rename from docs/extensions/wikilinks.txt rename to docs/extensions/wikilinks.md index 948b957f8..c2cd7358a 100644 --- a/docs/extensions/wikilinks.txt +++ b/docs/extensions/wikilinks.md @@ -1,8 +1,4 @@ -title: WikiLinks Extension -prev_title: Table of Contents Extension -prev_url: toc.html -next_title: Extension API -next_url: api.html +title: WikiLinks Extension WikiLinks ========= @@ -46,10 +42,10 @@ becomes Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.wikilinks` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.wikilinks` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The default behavior is to point each link to the document root of the current @@ -111,7 +107,7 @@ Would cause all WikiLinks to be assigned to the class `myclass`. Using with Meta-Data extension ------------------------------ -The WikiLink extension also supports the [Meta-Data](meta_data.html) extension. +The WikiLink extension also supports the [Meta-Data](meta_data.md) extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are: diff --git a/docs/siteindex.md b/docs/siteindex.md deleted file mode 100644 index 0139bd7c8..000000000 --- a/docs/siteindex.md +++ /dev/null @@ -1,78 +0,0 @@ -title: Table of Contents -prev_title: Authors -prev_url: authors.html -next_title: Summary -next_url: index.html - -Table of Contents -================= - -* [Python Markdown](index.html) - * [Goals](index.html#goals) - * [Features](index.html#features) - * [Differences](index.html#differences) - * [Support](index.html#support) -* [Installation](install.html) - * [The Easy Way](install.html#the-easy-way) - * [Installing on Windows](install.html#windows) - * [Installing on *nix Systems](install.html#linux) - * [Using the Git Repository](install.html#git) - * [Dependencies](install.html#dependencies) -* [Library Reference](reference.html) - * [The Basics](reference.html#the-basics) - * [The Details](reference.html#the-details) - * [`markdown.markdown`](reference.html#markdown) - * [`markdown.markdownFromFile`](reference.html#markdownFromFile) - * [`markdown.Markdown`](reference.html#Markdown) -* [Command Line](cli.html) - * [Setup](cli.html#setup) - * [Usage](cli.html#usage) - * [Using Extensions](cli.html#using-extensions) -* [Extensions](extensions/index.html) - * [Officially Supported Extensions](extensions/index.html#officially-supported-extensions) - * [Extra](extensions/extra.html) - * [Abbreviations](extensions/abbreviations.html) - * [Attribute Lists](extensions/attr_list.html) - * [Definition Lists](extensions/definition_lists.html) - * [Fenced Code Blocks](extensions/fenced_code_blocks.html) - * [Footnotes](extensions/footnotes.html) - * [Tables](extensions/tables.html) - * [Smart Strong](extensions/smart_strong.html) - * [Admonition](extensions/admonition.html) - * [CodeHilite](extensions/code_hilite.html) - * [HeaderId](extensions/header_id.html) - * [Meta-Data](extensions/meta_data.html) - * [New Line to Break](extensions/nl2br.html) - * [Sane Lists](extensions/sane_lists.html) - * [SmartyPants](extensions/smarty.html) - * [Table of Contents](extensions/toc.html) - * [WikiLinks](extensions/wikilinks.html) - * [Third Party Extensions](extensions/index.html#third-party-extensions) - * [Extension API](extensions/api.html) - * [Preprocessors](extensions/api.html#preprocessors) - * [Inline Patterns](extensions/api.html#inlinepatterns) - * [Treeprocessors](extensions/api.html#treeprocessors) - * [Postprocessors](extensions/api.html#postprocessors) - * [BlockParser](extensions/api.html#blockparser) - * [Working with the ElementTree](extensions/api.html#working_with_et) - * [Integrating your code into Markdown](extensions/api.html#integrating_into_markdown) - * [extendMarkdown](extensions/api.html#extendmarkdown) - * [OrderedDict](extensions/api.html#ordereddict) - * [registerExtension](extensions/api.html#registerextension) - * [Configuration Settings](extensions/api.html#configsettings) - * [makeExtension](extensions/api.html#makeextension) -* [Test Suite](test_suite.html) - * [Markdown Syntax Test](test_suite.html#markdown-syntax-tests) - * [Syntax Test Configuration Settings](test_suite.html#syntax-test-config-settings) - * [Unit Tests](test_suite.html#unit-tests) -* [Change Log](change_log.html) - * [Release Notes for v.2.6](release-2.6.html) - * [Release Notes for v.2.5](release-2.5.html) - * [Release Notes for v.2.4](release-2.4.html) - * [Release Notes for v.2.3](release-2.3.html) - * [Release Notes for v.2.2.1](release-2.1.1.html) - * [Release Notes for v.2.2.0](release-2.1.0.html) - * [Release Notes for v.2.0.2](release-2.0.2.html) - * [Release Notes for v.2.0.1](release-2.0.1.html) - * [Release Notes for v.2.0](release-2.0.html) -* [Authors](authors.html) diff --git a/mkdocs.yml b/mkdocs.yml index 510524a19..f55dd22d4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,6 +18,24 @@ pages: - Library Reference: reference.md - Command Line: cli.md - Extensions: extensions/index.md + - Officially Supported Extensions: + - Abbreviations: extensions/abbreviations.md + - Admonition: extensions/admonition.md + - Attribute Lists: extensions/attr_list.md + - CodeHilite: extensions/code_hilite.md + - Definition Lists: extensions/definition_lists.md + - Extra: extensions/extra.md + - Fenced Code Blocks: extensions/fenced_code_blocks.md + - Footnotes: extensions/footnotes.md + - HeaderId: extensions/header_id.md + - Meta-Data: extensions/meta_data.md + - New Line to Break: extensions/nl2br.md + - Sane Lists: extensions/sane_lists.md + - SmartyPants: extensions/smarty.md + - Smart Strong: extensions/smart_strong.md + - Table of Contents: extensions/toc.md + - Tables: extensions/tables.md + - WikiLinks: extensions/wikilinks.md - Extension API: extensions/api.md - Test Suite: test_suite.md - Change Log: change_log/index.md From 87ca5f6ebfad7951d333c2299088ebe86860c593 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 6 Dec 2017 15:49:47 -0500 Subject: [PATCH 3/7] pythonhost.org/Markdown => Python-Markdown.github.io --- INSTALL.md | 2 +- README.md | 10 +++++----- markdown/__init__.py | 2 +- markdown/__main__.py | 2 +- markdown/extensions/abbr.py | 2 +- markdown/extensions/admonition.py | 2 +- markdown/extensions/attr_list.py | 2 +- markdown/extensions/codehilite.py | 2 +- markdown/extensions/def_list.py | 2 +- markdown/extensions/extra.py | 2 +- markdown/extensions/fenced_code.py | 2 +- markdown/extensions/footnotes.py | 2 +- markdown/extensions/headerid.py | 2 +- markdown/extensions/meta.py | 2 +- markdown/extensions/nl2br.py | 2 +- markdown/extensions/sane_lists.py | 2 +- markdown/extensions/smart_strong.py | 2 +- markdown/extensions/smarty.py | 2 +- markdown/extensions/tables.py | 2 +- markdown/extensions/toc.py | 2 +- markdown/extensions/wikilinks.py | 2 +- mkdocs.yml | 2 +- setup.py | 6 +++--- tests/misc/em-around-links.html | 10 +++++----- tests/misc/em-around-links.txt | 10 +++++----- 25 files changed, 39 insertions(+), 39 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 95fbfd125..a314fb6c7 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -6,4 +6,4 @@ As an Admin/Root user on your system do: pip install markdown Or for more specific instructions, view the documentation in `docs/install.md` -or on the website at . +or on the website at . diff --git a/README.md b/README.md index 0f5b673ed..075cb05f2 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,10 @@ though there are a few known issues. See [Features][] for information on what exactly is supported and what is not. Additional features are supported by the [Available Extensions][]. -[Python-Markdown]: https://pythonhosted.org/Markdown/ +[Python-Markdown]: https://Python-Markdown.github.io/ [Markdown]: http://daringfireball.net/projects/markdown/ -[Features]: https://pythonhosted.org/Markdown/index/#Features -[Available Extensions]: https://pythonhosted.org/Markdown/extensions/ +[Features]: https://Python-Markdown.github.io#Features +[Available Extensions]: https://Python-Markdown.github.io/extensions Documentation @@ -25,9 +25,9 @@ Documentation Installation and usage documentation is available in the `docs/` directory of the distribution and on the project website at -. +. -See the change log at . +See the change log at . Support ------- diff --git a/markdown/__init__.py b/markdown/__init__.py index 409f9cfd4..5b8be470d 100644 --- a/markdown/__init__.py +++ b/markdown/__init__.py @@ -10,7 +10,7 @@ import markdown html = markdown.markdown(your_text_string) -See for more +See for more information and instructions on how to extend the functionality of Python Markdown. Read that before you try modifying this file. diff --git a/markdown/__main__.py b/markdown/__main__.py index 17bfa9f3c..c24f7562c 100644 --- a/markdown/__main__.py +++ b/markdown/__main__.py @@ -27,7 +27,7 @@ def parse_options(args=None, values=None): usage = """%prog [options] [INPUTFILE] (STDIN is assumed if no INPUTFILE is given)""" desc = "A Python implementation of John Gruber's Markdown. " \ - "https://pythonhosted.org/Markdown/" + "https://Python-Markdown.github.io/" ver = "%%prog %s" % markdown.version parser = optparse.OptionParser(usage=usage, description=desc, version=ver) diff --git a/markdown/extensions/abbr.py b/markdown/extensions/abbr.py index 353d126f6..bfa8c10b0 100644 --- a/markdown/extensions/abbr.py +++ b/markdown/extensions/abbr.py @@ -4,7 +4,7 @@ This extension adds abbreviation handling to Python-Markdown. -See +See for documentation. Oringinal code Copyright 2007-2008 [Waylan Limberg](http://achinghead.com/) and diff --git a/markdown/extensions/admonition.py b/markdown/extensions/admonition.py index 0c5ce4669..2e83900be 100644 --- a/markdown/extensions/admonition.py +++ b/markdown/extensions/admonition.py @@ -6,7 +6,7 @@ [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions # noqa -See +See for documentation. Original code Copyright [Tiago Serafim](http://www.tiagoserafim.com/). diff --git a/markdown/extensions/attr_list.py b/markdown/extensions/attr_list.py index a7f92b66d..894e5455e 100644 --- a/markdown/extensions/attr_list.py +++ b/markdown/extensions/attr_list.py @@ -6,7 +6,7 @@ [maruku](http://maruku.rubyforge.org/proposal.html#attribute_lists)'s feature of the same name. -See +See for documentation. Original code Copyright 2011 [Waylan Limberg](http://achinghead.com/). diff --git a/markdown/extensions/codehilite.py b/markdown/extensions/codehilite.py index 20b889c44..ee42d57c8 100644 --- a/markdown/extensions/codehilite.py +++ b/markdown/extensions/codehilite.py @@ -4,7 +4,7 @@ Adds code/syntax highlighting to standard Python-Markdown code blocks. -See +See for documentation. Original code Copyright 2006-2008 [Waylan Limberg](http://achinghead.com/). diff --git a/markdown/extensions/def_list.py b/markdown/extensions/def_list.py index 77cca6eb8..9057ebd98 100644 --- a/markdown/extensions/def_list.py +++ b/markdown/extensions/def_list.py @@ -4,7 +4,7 @@ Adds parsing of Definition Lists to Python-Markdown. -See +See for documentation. Original code Copyright 2008 [Waylan Limberg](http://achinghead.com) diff --git a/markdown/extensions/extra.py b/markdown/extensions/extra.py index de5db03cd..587ba6402 100644 --- a/markdown/extensions/extra.py +++ b/markdown/extensions/extra.py @@ -20,7 +20,7 @@ variable defined below, but be aware that such changes may be lost when you upgrade to any future version of Python-Markdown. -See +See for documentation. Copyright The Python Markdown Project diff --git a/markdown/extensions/fenced_code.py b/markdown/extensions/fenced_code.py index 277bac405..392c654e3 100644 --- a/markdown/extensions/fenced_code.py +++ b/markdown/extensions/fenced_code.py @@ -4,7 +4,7 @@ This extension adds Fenced Code Blocks to Python-Markdown. -See +See for documentation. Original code Copyright 2007-2008 [Waylan Limberg](http://achinghead.com/). diff --git a/markdown/extensions/footnotes.py b/markdown/extensions/footnotes.py index 8bd85959c..7edf8135c 100644 --- a/markdown/extensions/footnotes.py +++ b/markdown/extensions/footnotes.py @@ -4,7 +4,7 @@ Adds footnote handling to Python-Markdown. -See +See for documentation. Copyright The Python Markdown Project diff --git a/markdown/extensions/headerid.py b/markdown/extensions/headerid.py index 2cb20b97a..fdcc8f206 100644 --- a/markdown/extensions/headerid.py +++ b/markdown/extensions/headerid.py @@ -4,7 +4,7 @@ Auto-generate id attributes for HTML headers. -See +See for documentation. Original code Copyright 2007-2011 [Waylan Limberg](http://achinghead.com/). diff --git a/markdown/extensions/meta.py b/markdown/extensions/meta.py index 711235ef4..7902bd437 100644 --- a/markdown/extensions/meta.py +++ b/markdown/extensions/meta.py @@ -4,7 +4,7 @@ This extension adds Meta Data handling to markdown. -See +See for documentation. Original code Copyright 2007-2008 [Waylan Limberg](http://achinghead.com). diff --git a/markdown/extensions/nl2br.py b/markdown/extensions/nl2br.py index 8acd60c2e..a4c0fab02 100644 --- a/markdown/extensions/nl2br.py +++ b/markdown/extensions/nl2br.py @@ -5,7 +5,7 @@ A Python-Markdown extension to treat newlines as hard breaks; like GitHub-flavored Markdown does. -See +See for documentation. Oringinal code Copyright 2011 [Brian Neal](http://deathofagremmie.com/) diff --git a/markdown/extensions/sane_lists.py b/markdown/extensions/sane_lists.py index 828ae7ab3..651b12b25 100644 --- a/markdown/extensions/sane_lists.py +++ b/markdown/extensions/sane_lists.py @@ -4,7 +4,7 @@ Modify the behavior of Lists in Python-Markdown to act in a sane manor. -See +See for documentation. Original code Copyright 2011 [Waylan Limberg](http://achinghead.com) diff --git a/markdown/extensions/smart_strong.py b/markdown/extensions/smart_strong.py index 58570bb55..eeded3114 100644 --- a/markdown/extensions/smart_strong.py +++ b/markdown/extensions/smart_strong.py @@ -4,7 +4,7 @@ This extention adds smarter handling of double underscores within words. -See +See for documentation. Original code Copyright 2011 [Waylan Limberg](http://achinghead.com) diff --git a/markdown/extensions/smarty.py b/markdown/extensions/smarty.py index 600d74cd6..5031bc402 100644 --- a/markdown/extensions/smarty.py +++ b/markdown/extensions/smarty.py @@ -6,7 +6,7 @@ Adds conversion of ASCII dashes, quotes and ellipses to their HTML entity equivalents. -See +See for documentation. Author: 2013, Dmitry Shachnev diff --git a/markdown/extensions/tables.py b/markdown/extensions/tables.py index ec3b6ac9f..6d28aefff 100644 --- a/markdown/extensions/tables.py +++ b/markdown/extensions/tables.py @@ -4,7 +4,7 @@ Added parsing of tables to Python-Markdown. -See +See for documentation. Original code Copyright 2009 [Waylan Limberg](http://achinghead.com) diff --git a/markdown/extensions/toc.py b/markdown/extensions/toc.py index 56db33c50..2c4a4b54e 100644 --- a/markdown/extensions/toc.py +++ b/markdown/extensions/toc.py @@ -2,7 +2,7 @@ Table of Contents Extension for Python-Markdown =============================================== -See +See for documentation. Oringinal code Copyright 2008 [Jack Miller](http://codezen.org) diff --git a/markdown/extensions/wikilinks.py b/markdown/extensions/wikilinks.py index 94e1b6794..ff16494b9 100644 --- a/markdown/extensions/wikilinks.py +++ b/markdown/extensions/wikilinks.py @@ -4,7 +4,7 @@ Converts [[WikiLinks]] to relative links. -See +See for documentation. Original code Copyright [Waylan Limberg](http://achinghead.com/). diff --git a/mkdocs.yml b/mkdocs.yml index f55dd22d4..2e3d45960 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: Python-Markdown -site_url: https://Python-Markdown.github.io +site_url: https://Python-Markdown.github.io/ repo_url: https://github.com/Python-Markdown/markdown site_author: "The Python-Markdown Project" copyright: "Copyright © 2010-2017" diff --git a/setup.py b/setup.py index 51b092aa9..fba517215 100755 --- a/setup.py +++ b/setup.py @@ -72,8 +72,8 @@ def run(self): supported by the `Available Extensions`_. .. _Markdown: http://daringfireball.net/projects/markdown/ -.. _Features: https://pythonhosted.org/Markdown/#Features -.. _`Available Extensions`: https://pythonhosted.org/Markdown/extensions/ +.. _Features: https://Python-Markdown.github.io#Features +.. _`Available Extensions`: https://Python-Markdown.github.io/extensions/ Support ======= @@ -88,7 +88,7 @@ def run(self): setup( name='Markdown', version=version, - url='https://pythonhosted.org/Markdown/', + url='https://Python-Markdown.github.io/', download_url='http://pypi.python.org/packages/source/M/Markdown/Markdown-%s.tar.gz' % version, description='Python implementation of Markdown.', long_description=long_description, diff --git a/tests/misc/em-around-links.html b/tests/misc/em-around-links.html index a7593c517..cc415f505 100644 --- a/tests/misc/em-around-links.html +++ b/tests/misc/em-around-links.html @@ -1,13 +1,13 @@

    Title

    -

    Python in Markdown by some +

    Python in Markdown by some great folks - This does work as expected.

    \ No newline at end of file diff --git a/tests/misc/em-around-links.txt b/tests/misc/em-around-links.txt index de04d3b7c..dbc36443b 100644 --- a/tests/misc/em-around-links.txt +++ b/tests/misc/em-around-links.txt @@ -1,14 +1,14 @@ # Title - - *[Python in Markdown](https://pythonhosted.org/Markdown/) by some + - *[Python in Markdown](http://example.com) by some great folks* - This *does* work as expected. - - _[Python in Markdown](https://pythonhosted.org/Markdown/) by some + - _[Python in Markdown](http://example.com) by some great folks_ - This *does* work as expected. - - [_Python in Markdown_](https://pythonhosted.org/Markdown/) by some + - [_Python in Markdown_](http://example.com) by some great folks - This *does* work as expected. - - [_Python in Markdown_](https://pythonhosted.org/Markdown/) _by some + - [_Python in Markdown_](http://example.com) _by some great folks_ - This *does* work as expected. -_[Python in Markdown](https://pythonhosted.org/Markdown/) by some +_[Python in Markdown](http://example.com) by some great folks_ - This *does* work as expected. From dd56b87d2be8ed67a388dd8f4522be430abce399 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 6 Dec 2017 16:19:34 -0500 Subject: [PATCH 4/7] Automate pages deployment Assumes a git remote is set up named "pages". Do git remote add pages https://github.com/Python-Markdown/Python-Markdown.github.io.git ... before running `make deploy` the first time. --- makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/makefile b/makefile index 7a78213b8..aeb81aab5 100644 --- a/makefile +++ b/makefile @@ -22,6 +22,7 @@ install: deploy: python setup.py sdist --manifest-only python setup.py sdist --formats zip,gztar upload + mkdocs gh-deploy -r pages -b master .PHONY : build build: @@ -36,7 +37,6 @@ build-win: .PHONY : docs docs: mkdocs build --clean - cd site && zip -r ../docs.zip . .PHONY : test test: @@ -62,4 +62,5 @@ clean: rm -rf build rm -rf dist rm -rf tmp + rm -rf site # git clean -dfx' From 23985652e1391dd9c05197b934672e54e46b954b Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 6 Dec 2017 18:34:42 -0500 Subject: [PATCH 5/7] Restore some md3 branch deletions which are not (yet) relevent. --- docs/change_log/release-2.1.md | 90 +++++++++++++++---------------- docs/change_log/release-2.2.md | 32 ++++++------ docs/change_log/release-2.3.md | 44 ++++++++-------- docs/change_log/release-2.4.md | 28 ++++++---- docs/change_log/release-2.5.md | 96 ++++++++++++++++++---------------- docs/change_log/release-2.6.md | 40 ++++++++------ docs/extensions/index.md | 80 ++++++++++++++-------------- docs/index.md | 68 ++++++++++++------------ 8 files changed, 251 insertions(+), 227 deletions(-) diff --git a/docs/change_log/release-2.1.md b/docs/change_log/release-2.1.md index ad75ac986..52697b55d 100644 --- a/docs/change_log/release-2.1.md +++ b/docs/change_log/release-2.1.md @@ -3,14 +3,14 @@ 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, +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 +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 @@ -19,34 +19,34 @@ 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 +* 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 +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 +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 +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 +* If you have been using the [HeaderId](../extensions.md) extension +to define custom ids on headers, you will want to switch to using the new +[Attribute List](../extensions/attr_list.md) extension. The HeaderId extension +now only auto-generates ids on headers which have not already had ids defined. +Note that the [Extra](../extensions/extra.md) 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 @@ -63,25 +63,25 @@ 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 +Three new extensions were added. [Attribute Lists](../extensions/attr_list.md), +which was inspired by Maruku's feature of the same name, +[Newline to Break](../extensions/nl2br.md), which was inspired by GitHub +Flavored Markdown, and [Smart Strong](../extensions/smart_strong.md), which fills a hole in the Extra extension. -HTML5 is now supported. All this really means is that new block level elements +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 +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 +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., `

    `) which can choke +more invalid output like empty elements (i.e., `

    `) which can choke browsers. -Improved support for Python 3.x. Now when running `setupy.py install` in -Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 +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. @@ -89,30 +89,30 @@ 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 +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 +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 +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 +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 +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 +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 +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/Python-Markdown/markdown/commits/master) for a +Various bug fixes have been made, which are too numerous to list here. See the +[commit log](https://github.com/Python-Markdown/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 index 5533eadf2..1f2a68bc0 100644 --- a/docs/change_log/release-2.2.md +++ b/docs/change_log/release-2.2.md @@ -3,12 +3,12 @@ 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 +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. +Python-Markdown supports Python versions 2.5, 2.6, 2.7, 3.1, and 3.2 out +of the box. Backwards-incompatible Changes ------------------------------ @@ -16,13 +16,13 @@ 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 +* 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 `` and `` tags in +* For many years Python-Markdown has identified `` and `` 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 @@ -30,21 +30,21 @@ 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 +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 +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 +The docs were refactored and can now be found at . 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 +The [Sane_Lists](../extensions/sane_lists.md) +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. @@ -56,9 +56,9 @@ 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 +`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/Python-Markdown/markdown/commits/master) +Various bug fixes have been made. See the +[commit log](https://github.com/Python-Markdown/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 index 449db6aed..fb3d96224 100644 --- a/docs/change_log/release-2.3.md +++ b/docs/change_log/release-2.3.md @@ -4,8 +4,8 @@ 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 +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. @@ -15,17 +15,17 @@ 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 +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, +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 - +'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 @@ -36,24 +36,25 @@ 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` +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. +[CodeHilite Extension]: ../extensions/codehilite.md * 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 +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: +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 @@ -65,16 +66,17 @@ What's New in Python-Markdown 2.3 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 +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 +* 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. +[Admonition Extension]: ../extensions/admonition.md [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions * Various bug fixes have been made. See the diff --git a/docs/change_log/release-2.4.md b/docs/change_log/release-2.4.md index c6a3034e4..5b279839a 100644 --- a/docs/change_log/release-2.4.md +++ b/docs/change_log/release-2.4.md @@ -13,12 +13,14 @@ 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 +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. +[CodeHilite Extension]: ../extensions/codehilite.md + * 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. @@ -26,31 +28,34 @@ 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. +* 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 +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 +[Smarty Extension]: ../extensions/smarty.md [SmartyPants]: http://daringfireball.net/projects/smartypants/ -* The Table of Contents Extension now supports new `permalink` option +* The [Table of Contents Extension] now supports new `permalink` option for creating [Sphinx]-style anchor links. +[Table of Contents Extension]: ../extensions/toc.md [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 +appending `markdown=1` to opening tag attributes. See [Markdown Inside HTML +Blocks] section for details. Thanks to [ryneeverett] for implementing this feature. +[Markdown Inside HTML Blocks]: ../extensions/extra.md#nested-markdown-inside-html-blocks [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): +the [Fenced Code Extension]): ```.python hl_lines="1 3" # This line will be emphasized. @@ -60,6 +65,7 @@ the Fenced Code Extension): Thanks to [A. Jesse Jiryu Davis] for implementing this feature. +[Fenced Code Extension]: ../extensions/fenced_code_blocks.md [A. Jesse Jiryu Davis]: https://github.com/ajdavis * Various bug fixes have been made. See the diff --git a/docs/change_log/release-2.5.md b/docs/change_log/release-2.5.md index fe7a800c1..06ffeaf5e 100644 --- a/docs/change_log/release-2.5.md +++ b/docs/change_log/release-2.5.md @@ -11,20 +11,23 @@ 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 +* 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 +* 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`][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 +[CodeHilite Extension]: ../extensions/code_hilite.md +[linenums]: ../extensions/code_hilite.md#usage + +* 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 + "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. @@ -60,23 +63,23 @@ Backwards-incompatible Changes 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 + 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 + 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 + 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']) @@ -92,47 +95,48 @@ Backwards-incompatible Changes 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) +* 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 +* 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 + languages other than English. Thanks to [Martin Altmayer] for implementing this feature. +[Smarty Extension]: ../extensions/smarty.md [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. +* 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. + 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 + + 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, + 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 @@ -140,13 +144,13 @@ What's New in Python-Markdown 2.5 [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 +* 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 + 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. @@ -154,11 +158,11 @@ What's New in Python-Markdown 2.5 [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 +* 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 + 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 @@ -166,10 +170,12 @@ What's New in Python-Markdown 2.5 [JSON]: http://json.org/ [PyYAML]: http://pyyaml.org/ -* The Admonition Extension is no longer considered "experimental." +* The [Admonition Extension][ae] is no longer considered "experimental." + +[ae]: ../extensions/admonition.md * 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 + will not directly effect end users, the code is being better tested which will benefit everyone. * Various bug fixes have been made. See the diff --git a/docs/change_log/release-2.6.md b/docs/change_log/release-2.6.md index aeff75067..7e7f82f0e 100644 --- a/docs/change_log/release-2.6.md +++ b/docs/change_log/release-2.6.md @@ -13,11 +13,11 @@ Backwards-incompatible Changes ### `safe_mode` Deprecated -Both `safe_mode` and the associated `html_replacement_text` keywords are 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 +"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. @@ -62,9 +62,9 @@ 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 + 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. @@ -72,7 +72,7 @@ Then it is recommended that you change it to read something like this: 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 +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 @@ -105,19 +105,19 @@ of the current behavior. ### Extension Configuration as Part of Extension Name Deprecated -The previously documented method of appending the extension configuration options as +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) +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 +The [HeaderId][hid] 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 +[Table of Contents][TOC] 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 @@ -125,6 +125,8 @@ 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`). +[hid]: ../extensions/header_id.md + ### The `configs` Keyword is Deprecated Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class @@ -187,7 +189,7 @@ worked on PyPy for some time, it is now officially supported and tested on PyPy. ### YAML Style Meta-Data -The Meta-Data Extension now includes optional support for [YAML] style +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. @@ -198,12 +200,13 @@ party extension be used if you want true YAML support. See [Issue #390][#390] fo explanation. [MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata +[Meta-Data]: ../extensions/meta_data.md [YAML]: http://yaml.org/ [#390]: https://github.com/Python-Markdown/markdown/issues/390 ### Table of Contents Extension Refactored -The Table of Contents Extension has been refactored and some new features +The [Table of Contents][TOC] Extension has been refactored and some new features have been added. See the documentation for a full explanation of each feature listed below: @@ -227,23 +230,26 @@ listed below: 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. +[TOC]: ../extensions/toc.md + ### Pygments can now be disabled -The CodeHilite Extension has gained a new configuration option: `use_pygments`. +The [CodeHilite][ch] 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 +Pygments'. If a language is defined for a code block, it will be assigned to the `` 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. +[ch]: ../extensions/code_hilite.md [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 +will not directly effect end users, the code is being better tested which will benefit everyone. [flake8]: https://flake8.readthedocs.io/en/latest/ diff --git a/docs/extensions/index.md b/docs/extensions/index.md index 23c4133b7..1e05ddd07 100644 --- a/docs/extensions/index.md +++ b/docs/extensions/index.md @@ -13,7 +13,7 @@ To use an extension, pass it to markdown with the `extensions` keyword. See the [Library Reference](../reference.md#extensions) for more details. -From the command line, specify an extension with the `-x` option. +From the command line, specify an extension with the `-x` option. $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html @@ -26,47 +26,49 @@ See the [Command Line docs](../cli.md) or use the `--help` option for more detai Officially Supported Extensions ------------------------------- -The extensions listed below are maintained and officially supported by -the Python-Markdown team. However, no extensions ship with Python-Markdown -by default. If you would like to use any of the extensions listed below, -you will need to install each of them individually. See the documentation -for each extension for specifics in instalation and usage. +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 using the "name" listed in the second column below. Extension | "Name" ------------------------------------ | --------------- -[Extra] | `extra` -    [Abbreviations][] | `abbr` -    [Attribute Lists][] | `attr_list` -    [Definition Lists][] | `def_list` -    [Fenced Code Blocks][] | `fenced_code` -    [Footnotes][] | `footnotes` -    [Tables][] | `tables` -    [Smart Strong][] | `smart_strong` -[Admonition][] | `admonition` -[CodeHilite][] | `codehilite` -[Meta-Data] | `meta` -[New Line to Break] | `nl2br` -[Sane Lists] | `sane_lists` -[SmartyPants] | `smarty` -[Table of Contents] | `toc` -[WikiLinks] | `wikilinks` - -[Extra]: https://github.com/Python-Markdown/mdx_extra -[Abbreviations]: https://github.com/Python-Markdown/mdx_abbreviations -[Attribute Lists]: https://github.com/Python-Markdown/mdx_attr_list -[Definition Lists]: https://github.com/Python-Markdown/mdx_definition_lists -[Fenced Code Blocks]: https://github.com/Python-Markdown/mdx_fenced_code_blocks -[Footnotes]: https://github.com/Python-Markdown/mdx_footnotes -[Tables]: https://github.com/Python-Markdown/mdx_tables -[Smart Strong]: https://github.com/Python-Markdown/mdx_smart_strong -[Admonition]: https://github.com/Python-Markdown/mdx_admonition -[CodeHilite]: https://github.com/Python-Markdown/mdx_code_hilite -[Meta-Data]: https://github.com/Python-Markdown/mdx_meta_data -[New Line to Break]: https://github.com/Python-Markdown/mdx_nl2br -[Sane Lists]: https://github.com/Python-Markdown/mdx_sane_lists -[SmartyPants]: https://github.com/Python-Markdown/mdx_smarty -[Table of Contents]: https://github.com/Python-Markdown/mdx_toc -[WikiLinks]: https://github.com/Python-Markdown/mdx_wikilinks +[Extra] | `markdown.extensions.extra` +    [Abbreviations][] | `markdown.extensions.abbr` +    [Attribute Lists][] | `markdown.extensions.attr_list` +    [Definition Lists][] | `markdown.extensions.def_list` +    [Fenced Code Blocks][] | `markdown.extensions.fenced_code` +    [Footnotes][] | `markdown.extensions.footnotes` +    [Tables][] | `markdown.extensions.tables` +    [Smart Strong][] | `markdown.extensions.smart_strong` +[Admonition][] | `markdown.extensions.admonition` +[CodeHilite][] | `markdown.extensions.codehilite` +[HeaderId] | `markdown.extensions.headerid` +[Meta-Data] | `markdown.extensions.meta` +[New Line to Break] | `markdown.extensions.nl2br` +[Sane Lists] | `markdown.extensions.sane_lists` +[SmartyPants] | `markdown.extensions.smarty` +[Table of Contents] | `markdown.extensions.toc` +[WikiLinks] | `markdown.extensions.wikilinks` + +[Extra]: extra.md +[Abbreviations]: abbreviations.md +[Attribute Lists]: attr_list.md +[Definition Lists]: definition_lists.md +[Fenced Code Blocks]: fenced_code_blocks.md +[Footnotes]: footnotes.md +[Tables]: tables.md +[Smart Strong]: smart_strong.md +[Admonition]: admonition.md +[CodeHilite]: code_hilite.md +[HeaderId]: header_id.md +[Meta-Data]: meta_data.md +[New Line to Break]: nl2br.md +[Sane Lists]: sane_lists.md +[SmartyPants]: smarty.md +[Table of Contents]: toc.md +[WikiLinks]: wikilinks.md Third Party Extensions ---------------------- diff --git a/docs/index.md b/docs/index.md index 1bb7699a1..a123395fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,11 +3,11 @@ title: Python-Markdown Python-Markdown =============== -This is a Python implementation of John Gruber's -[Markdown](http://daringfireball.net/projects/markdown/). +This is a Python implementation of John Gruber's +[Markdown](http://daringfireball.net/projects/markdown/). It is almost completely compliant with the reference implementation, -though there are a few very minor [differences](#differences). See John's -[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) +though there are a few very minor [differences](#differences). See John's +[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) for the syntax rules. See the [installation instructions](install.md) to get started. @@ -18,8 +18,8 @@ Goals The Python-Markdown project is developed with the following goals in mind: * Maintain a Python 2 *and* Python 3 library (with an optional CLI wrapper) - suited to use in web server environments (never raise an exception, never - write to stdout, etc.) as an implementation of the markdown parser that + suited to use in web server environments (never raise an exception, never + write to stdout, etc.) as an implementation of the markdown parser that follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax) and the behavior of the original (markdown.pl) implementation as reasonably as possible (see [differences](#differences) for a few exceptions). @@ -35,15 +35,16 @@ features: * __International Input__ - Python-Markdown will accept [input](reference.md#text) in any language - supported by Unicode including bi-directional text. In fact the test suite + Python-Markdown will accept [input](reference.md#text) in any language + supported by Unicode including bi-directional text. In fact the test suite includes documents written in Russian and Arabic. * __Extensions__ - Various [extensions](extensions/index.md) are avaiable to change and/or - extend the base syntax. Additionally, a public [Extension API](extensions/api.md) - is available to write your own extensions. + Various [extensions](extensions/index.md) are provided (including + [extra](extensions/extra.md)) to change and/or extend the base syntax. + Additionally, a public [Extension API](extensions/api.md) is available + to write your own extensions. * __Output Formats__ @@ -52,59 +53,60 @@ features: * __Command Line Interface__ - In addition to being a Python Library, a + In addition to being a Python Library, a [command line script](cli.md) is available for your convenience. Differences ----------- -While Python-Markdown strives to fully implement markdown as described in the -[syntax rules](http://daringfireball.net/projects/markdown/syntax), the rules -can be interpreted in different ways and different implementations -occasionally vary in their behavior (see the +While Python-Markdown strives to fully implement markdown as described in the +[syntax rules](http://daringfireball.net/projects/markdown/syntax), the rules +can be interpreted in different ways and different implementations +occasionally vary in their behavior (see the [Babelmark FAQ](http://johnmacfarlane.net/babelmark2/faq.html#what-are-some-examples-of-interesting-divergences-between-implementations) -for some examples). Known and intentional differences found in Python-Markdown +for some examples). Known and intentional differences found in Python-Markdown are summarized below: * __Middle-Word Emphasis__ Python-Markdown defaults to ignoring middle-word emphasis. In other words, `some_long_filename.txt` will not become `somelongfilename.txt`. - This can be disabled with an extension. + This can be switched off if desired. See the + [Library Reference](reference.html#smart_emphasis) for details. * __Indentation/Tab Length__ - The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list) - clearly state that when a list item consists of multiple paragraphs, "each - subsequent paragraph in a list item **must** be indented by either 4 spaces - or one tab" (emphasis added). However, many implementations do not enforce - this rule and allow less than 4 spaces of indentation. The implementers of - Python-Markdown consider it a bug to not enforce this rule. + The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list) + clearly state that when a list item consists of multiple paragraphs, "each + subsequent paragraph in a list item **must** be indented by either 4 spaces + or one tab" (emphasis added). However, many implementations do not enforce + this rule and allow less than 4 spaces of indentation. The implementers of + Python-Markdown consider it a bug to not enforce this rule. This applies to any block level elements nested in a list, including - paragraphs, sub-lists, blockquotes, code blocks, etc. They **must** always + paragraphs, sub-lists, blockquotes, code blocks, etc. They **must** always be indented by at least four spaces (or one tab) for each level of nesting. In the event that one would prefer different behavior, - [tab_length](reference.md#tab_length) can be set to whatever length is - desired. Be warned however, as this will affect indentation for all aspects + [tab_length](reference.md#tab_length) can be set to whatever length is + desired. Be warned however, as this will affect indentation for all aspects of the syntax (including root level code blocks). * __Consecutive Lists__ While the syntax rules are not clear on this, many implementations (including the original) do not end one list and start a second list when the list marker - (asterisks, pluses, hyphens, and numbers) changes. For consistency, - Python-Markdown maintains the same behavior with no plans to change in the - foreseeable future. That said, the Sane List Extension + (asterisks, pluses, hyphens, and numbers) changes. For consistency, + Python-Markdown maintains the same behavior with no plans to change in the + foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.md) is available to provide a less surprising behavior. - + Support ------- -You may ask for help and discuss various other issues on the [mailing list][] +You may ask for help and discuss various other issues on the [mailing list][] and report bugs on the [bug tracker][]. [mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss -[bug tracker]: http://github.com/Python-Markdown/markdown/issues +[bug tracker]: http://github.com/Python-Markdown/markdown/issues From 6e209911ee13a9a0e8b219689da0665e30654ff5 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 6 Dec 2017 20:11:59 -0500 Subject: [PATCH 6/7] Misc cleanup. --- docs/change_log/release-2.1.md | 2 +- docs/change_log/release-2.3.md | 2 +- docs/change_log/release-2.4.md | 2 +- docs/cli.md | 108 +++--- docs/extensions/abbreviations.md | 22 +- docs/extensions/admonition.md | 56 +-- docs/extensions/api.md | 525 ++++++++++++++------------ docs/extensions/attr_list.md | 48 ++- docs/extensions/code_hilite.md | 38 +- docs/extensions/definition_lists.md | 31 +- docs/extensions/extra.md | 32 +- docs/extensions/fenced_code_blocks.md | 82 ++-- docs/extensions/footnotes.md | 51 +-- docs/extensions/header_id.md | 45 ++- docs/extensions/index.md | 8 +- docs/extensions/meta_data.md | 75 ++-- docs/extensions/nl2br.md | 20 +- docs/extensions/sane_lists.md | 54 +-- docs/extensions/smart_strong.md | 24 +- docs/extensions/smarty.md | 36 +- docs/extensions/tables.md | 48 +-- docs/extensions/toc.md | 59 +-- docs/extensions/wikilinks.md | 72 ++-- docs/index.md | 4 +- docs/install.md | 38 +- mkdocs.yml | 2 +- 26 files changed, 852 insertions(+), 632 deletions(-) diff --git a/docs/change_log/release-2.1.md b/docs/change_log/release-2.1.md index 52697b55d..a48162d9b 100644 --- a/docs/change_log/release-2.1.md +++ b/docs/change_log/release-2.1.md @@ -42,7 +42,7 @@ 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](../extensions.md) extension +* If you have been using the [HeaderId](../extensions/header_id.md) extension to define custom ids on headers, you will want to switch to using the new [Attribute List](../extensions/attr_list.md) extension. The HeaderId extension now only auto-generates ids on headers which have not already had ids defined. diff --git a/docs/change_log/release-2.3.md b/docs/change_log/release-2.3.md index fb3d96224..b9859483c 100644 --- a/docs/change_log/release-2.3.md +++ b/docs/change_log/release-2.3.md @@ -41,7 +41,7 @@ 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. -[CodeHilite Extension]: ../extensions/codehilite.md +[CodeHilite Extension]: ../extensions/code_hilite.md * 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 diff --git a/docs/change_log/release-2.4.md b/docs/change_log/release-2.4.md index 5b279839a..3eb046016 100644 --- a/docs/change_log/release-2.4.md +++ b/docs/change_log/release-2.4.md @@ -19,7 +19,7 @@ documentation for the [CodeHilite Extension] for an explanation of the new is set, but `force_linenos` will raise a `DeprecationWarning` and will likely be removed in a future version of Python-Markdown. -[CodeHilite Extension]: ../extensions/codehilite.md +[CodeHilite Extension]: ../extensions/code_hilite.md * URLs are no longer percent-encoded. This improves compatibility with the original (written in Perl) Markdown implementation. Please percent-encode diff --git a/docs/cli.md b/docs/cli.md index b6889e135..9fe8a3a9a 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -3,37 +3,45 @@ title: Command Line Using Python-Markdown on the Command Line ========================================= -While Python-Markdown is primarily a python library, a command line script is -included as well. While there are many other command line implementations -of Markdown, you may not have them installed, or you may prefer to use +While Python-Markdown is primarily a python library, a command line script is +included as well. While there are many other command line implementations +of Markdown, you may not have them installed, or you may prefer to use Python-Markdown's various extensions. Generally, you will want to have the Markdown library fully installed on your -system to run the command line script. See the +system to run the command line script. See the [Installation instructions](install.md) for details. Python-Markdown's command line script takes advantage of Python's `-m` flag. -Therefore, assuming the python executable is on your system path, use the +Therefore, assuming the python executable is on your system path, use the following format: - $ python -m markdown [options] [args] +```bash +python -m markdown [options] [args] +``` -That will run the module as a script with the options and arguments provided. +That will run the module as a script with the options and arguments provided. At its most basic usage, one would simply pass in a file name as the only argument: - $ python -m markdown input_file.txt +```bash +python -m markdown input_file.txt +``` -Piping input and output (on `STDIN` and `STDOUT`) is fully supported as well. +Piping input and output (on `STDIN` and `STDOUT`) is fully supported as well. For example: - $ echo "Some **Markdown** text." | python -m markdown > output.html +```bash +echo "Some **Markdown** text." | python -m markdown > output.html +``` Use the `--help` option for a list all available options and arguments: - $ python -m markdown --help +```bash +python -m markdown --help +``` -If you don't want to call the python executable directly (using the `-m` flag), +If you don't want to call the python executable directly (using the `-m` flag), follow the instructions below to use a wrapper script: Setup @@ -41,27 +49,27 @@ Setup Upon installation, the `markdown_py` script will have been copied to your Python "Scripts" directory. Different systems require different methods to -ensure that any files in the Python "Scripts" directory are on your system +ensure that any files in the Python "Scripts" directory are on your system path. * **Windows**: - Assuming a default install of Python on Windows, your "Scripts" directory + Assuming a default install of Python on Windows, your "Scripts" directory is most likely something like `C:\\Python26\Scripts`. Verify the location of your "Scripts" directory and add it to you system path. - Calling `markdown_py` from the command line will call the wrapper batch + Calling `markdown_py` from the command line will call the wrapper batch file `markdown_py.bat` in the `"Scripts"` directory created during install. * __*nix__ (Linux, OSX, BSD, Unix, etc.): - As each \*nix distribution is different and we can't possibly document all + As each \*nix distribution is different and we can't possibly document all of them here, we'll provide a few helpful pointers: - * Some systems will automatically install the script on your path. Try it + * Some systems will automatically install the script on your path. Try it and see if it works. Just run `markdown_py` from the command line. - * Other systems may maintain a separate "Scripts" ("bin") directory which + * Other systems may maintain a separate "Scripts" ("bin") directory which you need to add to your path. Find it (check with your distribution) and either add it to your path or make a symbolic link to it from your path. @@ -70,13 +78,13 @@ path. As an alternative, you could just `cd` into the directory which contains the source distribution, and run it from there. However, remember that your - markdown text files will not likely be in that directory, so it is much + markdown text files will not likely be in that directory, so it is much more convenient to have `markdown_py` on your path. -!!!Note +!!!Note Python-Markdown uses `"markdown_py"` as a script name because the Perl implementation has already taken the more obvious name "markdown". - Additionally, the default Python configuration on some systems would cause a + Additionally, the default Python configuration on some systems would cause a script named `"markdown.py"` to fail by importing itself rather than the markdown library. Therefore, the script has been named `"markdown_py"` as a compromise. If you prefer a different name for the script on your system, it is suggested that @@ -85,49 +93,62 @@ path. Usage ----- -To use `markdown_py` from the command line, run it as +To use `markdown_py` from the command line, run it as - $ markdown_py input_file.txt +```bash +markdown_py input_file.txt +``` -or +or - $ markdown_py input_file.txt > output_file.html +```bash +markdown_py input_file.txt > output_file.html +``` For a complete list of options, run - $ markdown_py --help +```bash +markdown_py --help +``` Using Extensions ---------------- -To load a Python-Markdown extension from the command line use the `-x` -(or `--extension`) option. The extension module must be on your `PYTHONPATH` -(see the [Extension API](extensions/api.md) for details). The extension can +To load a Python-Markdown extension from the command line use the `-x` +(or `--extension`) option. The extension module must be on your `PYTHONPATH` +(see the [Extension API](extensions/api.md) for details). The extension can then be invoked by the name of that module using Python's dot syntax: - $ python -m markdown -x path.to.module input.txt +```bash +python -m markdown -x path.to.module input.txt +``` To load multiple extensions, specify an `-x` option for each extension: - $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.codehilite input.txt +```bash +python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.codehilite input.txt +``` -If the extension supports configuration options (see the documentation for the -extension you are using to determine what settings it supports, if any), you +If the extension supports configuration options (see the documentation for the +extension you are using to determine what settings it supports, if any), you can pass them in as well: - $ python -m markdown -x markdown.extensions.footnotes -c config.yml input.txt +```bash +python -m markdown -x markdown.extensions.footnotes -c config.yml input.txt +``` The `-c` (or `--extension_configs`) option accepts a file name. The file must be in either the [YAML] or [JSON] format and contain YAML or JSON data that would map to -a Python Dictionary in the format required by the [`extension_configs`][ec] keyword -of the `markdown.Markdown` class. Therefore, the file `config.yaml` referenced in the +a Python Dictionary in the format required by the [`extension_configs`][ec] keyword +of the `markdown.Markdown` class. Therefore, the file `config.yaml` referenced in the above example might look like this: - markdown.extensions.footnotes: - PLACE_MARKER: ~~~~~~~~ - UNIQUE_IDS: True - -Note that while the `--extension_configs` option does specify the "markdown.extensions.footnotes" +```yaml +markdown.extensions.footnotes: + PLACE_MARKER: ~~~~~~~~ + UNIQUE_IDS: True +``` +Note that while the `--extension_configs` option does specify the "markdown.extensions.footnotes" extension, you still need to load the extension with the `-x` option, or the configuration for that extension will be ignored. @@ -136,8 +157,8 @@ installed on your system. JSON should work with no additional dependencies. The of your configuration file is automatically detected. !!!warning - The previously documented method of appending the extension configuration options as a string to the - extension name will be deprecated in Python-Markdown version 2.6. The `--extension_configs` + The previously documented method of appending the extension configuration options as a string to the + extension name will be deprecated in Python-Markdown version 2.6. The `--extension_configs` option should be used instead. See the [2.5 release notes] for more information. [ec]: reference.html#extension_configs @@ -145,4 +166,3 @@ of your configuration file is automatically detected. [JSON]: http://json.org/ [PyYAML]: http://pyyaml.org/ [2.5 release notes]: change_log/release-2.5.md - diff --git a/docs/extensions/abbreviations.md b/docs/extensions/abbreviations.md index c5e19dfc5..d580d5646 100644 --- a/docs/extensions/abbreviations.md +++ b/docs/extensions/abbreviations.md @@ -6,7 +6,7 @@ Abbreviations Summary ------- -The Abbreviations extension adds the ability to define abbreviations. +The Abbreviations extension adds the ability to define abbreviations. Specifically, any defined abbreviation is wrapped in an `` tag. The Abbreviations extension is included in the standard Markdown library. @@ -14,23 +14,27 @@ The Abbreviations extension is included in the standard Markdown library. Syntax ------ -Abbreviations are defined using the syntax established in +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 +```md +The HTML specification +is maintained by the W3C. + +*[HTML]: Hyper Text Markup Language +*[W3C]: World Wide Web Consortium +``` will be rendered as: -

    The HTML specification - is maintained by the W3C.

    +```html +

    The HTML specification +is maintained by the W3C.

    +``` Usage ----- diff --git a/docs/extensions/admonition.md b/docs/extensions/admonition.md index 1775bd206..3e0446de6 100644 --- a/docs/extensions/admonition.md +++ b/docs/extensions/admonition.md @@ -17,47 +17,59 @@ Syntax Admonitions are created using the following syntax: - !!! type "optional explicit title within double quotes" - Any number of other indented markdown elements. +```md +!!! type "optional explicit title within double quotes" + Any number of other indented markdown elements. - This is the second paragraph. + This is the second paragraph. +``` `type` will be used as the CSS class name and as default title. It must be a single word. So, for instance: - !!! note - You should note that the title will be automatically capitalized. +```md +!!! note + You should note that the title will be automatically capitalized. +``` will render: -
    -

    Note

    -

    You should note that the title will be automatically capitalized.

    -
    - +```html +
    +

    Note

    +

    You should note that the title will be automatically capitalized.

    +
    +``` Optionally, you can use custom titles. For instance: - !!! danger "Don't try this at home" - ... +```md +!!! danger "Don't try this at home" + ... +``` will render: -
    -

    Don't try this at home

    -

    ...

    -
    +```html +
    +

    Don't try this at home

    +

    ...

    +
    +``` If you don't want a title, use a blank string `""`: - !!! important "" - This is a admonition box without a title. +```md +!!! important "" + This is a admonition box without a title. +``` results in: -
    -

    This is a admonition box without a title.

    -
    - +```html +
    +

    This is a admonition box without a title.

    +
    +``` rST suggests the following `types`, but you're free to use whatever you want: attention, caution, danger, error, hint, important, note, tip, warning. diff --git a/docs/extensions/api.md b/docs/extensions/api.md index 1caa5c9b1..bcada342c 100644 --- a/docs/extensions/api.md +++ b/docs/extensions/api.md @@ -3,105 +3,111 @@ title: Extensions API Writing Extensions for Python-Markdown ====================================== -Python-Markdown includes an API for extension writers to plug their own +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, +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, +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][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 +As the parser builds an [ElementTree][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 +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 +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 +```python +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 +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()`**: +* **`getCompiledRegExp()`**: Returns a compiled regular expression. -* **`handleMatch(m)`**: +* **`handleMatch(m)`**: - Accepts a match object and returns an ElementTree element of a plain + Accepts a match object and returns an ElementTree element of a plain Unicode string. -Also, Inline Patterns can define the property `ANCESTOR_EXCLUDES` with either -a list or tuple of undesirable ancestors. The pattern should not match if it +Also, Inline Patterns can define the property `ANCESTOR_EXCLUDES` with either +a list or tuple of undesirable ancestors. The pattern should not match if it would cause the content to be a descendant of one of the defined tag names. 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 +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 +```python +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 +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) +```python +# 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 +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 `SimpleTagPattern` listed below. Feel free to use or extend any of the Pattern classes found at @@ -123,7 +129,7 @@ Feel free to use or extend any of the Pattern classes found at 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 +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. @@ -136,22 +142,24 @@ place. Additionally, the InlineProcessor is a Treeprocessor which steps through the tree and runs the Inline Patterns 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 ElementTree -object) and either modifies that root element and returns `None` or returns a +over-ride the `run` method which takes one argument `root` (an ElementTree +object) and either modifies that root element and returns `None` or returns a new ElementTree object. A pseudo example: - from markdown.treeprocessors import Treeprocessor +```python +from markdown.treeprocessors import Treeprocessor - class MyTreeprocessor(Treeprocessor): - def run(self, root): - root.text = 'modified content' +class MyTreeprocessor(Treeprocessor): + def run(self, root): + root.text = 'modified content' +``` -Note that Python class methods return `None` by default when no `return` +Note that Python class methods return `None` by default when no `return` statement is defined. Additionally all Python variables refer to objects by reference. Therefore, the above `run` method modifies the `root` element -in place and returns `None`. The changes made to the `root` element and its +in place and returns `None`. The changes made to the `root` element and its children are retained. Some may be inclined to return the modified `root` element. While that would @@ -159,29 +167,31 @@ work, it would cause a copy of the entire ElementTree to be generated each time the Treeprocessor is run. Therefore, it is generally expected that the `run` method would only return `None` or a new ElementTree object. -For specifics on manipulating the ElementTree, see +For specifics on manipulating the ElementTree, see [Working with the ElementTree][workingwithetree] below. Postprocessors {: #postprocessors } ----------------------------------- -Postprocessors manipulate the document after the ElementTree has been +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 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 +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 +```python +from markdown.postprocessors import Postprocessor - class TocPostprocessor(Postprocessor): - def run(self, text): - return MYMARKERRE.sub(MyToc, text) +class TocPostprocessor(Postprocessor): + def run(self, text): + return MYMARKERRE.sub(MyToc, text) +``` BlockParser {: #blockparser } ----------------------------- @@ -203,7 +213,7 @@ 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 +If it returns `False`, the BlockParser will move on to the next Blockprocessor. The **`test`** method takes two arguments: @@ -212,49 +222,49 @@ The **`test`** method takes two arguments: 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 +* **`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 ElementTree Element of the block. The run +* **`parent`**: A pointer to the parent ElementTree 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 ElementTree object is altered in place. -* **`blocks`**: A list of all remaining blocks of the document. Your run +* **`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 + 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 +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 +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)`**: +* **`lastChild(parent)`**: Returns the last child of the given ElementTree Element or `None` if it had no children. -* **`detab(text)`**: +* **`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)`**: +* **`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 + 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 @@ -264,19 +274,19 @@ stack is an instance of the `State` class. **`State`** is a subclass of `list` and has the additional methods: -* **`set(state)`**: +* **`set(state)`**: - Set a new state to string `state`. The new state is appended to the end + Set a new state to string `state`. The new state is appended to the end of the stack. -* **`reset()`**: +* **`reset()`**: - Step back one step in the stack. The last state at the end is removed from + Step back one step in the stack. The last state at the end is removed from the stack. -* **`isstate(state)`**: +* **`isstate(state)`**: - Test that the top (current) level of the stack is of the given string + Test that the top (current) level of the stack is of the given string `state`. Note that to ensure that the state stack does not become corrupted, each time a @@ -286,24 +296,24 @@ parsing that block. An instance of the **`BlockParser`** is found at `Markdown.parser`. `BlockParser` has the following methods: -* **`parseDocument(lines)`**: +* **`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 + 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)`**: +* **`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 + 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)`**: +* **`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 + 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 @@ -314,88 +324,96 @@ 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][ElementTree] object before serializing that back to Unicode text. -Markdown has provided some helpers to ease that manipulation within the context +As mentioned, the Markdown parser converts a source document to an +[ElementTree][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 +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 (ElementTree). In each instance, `cElementTree` is -tried first, then ElementTree if the faster C implementation is not +```python +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 (ElementTree). 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 +Sometimes you may want text inserted into an element to be parsed by [Inline Patterns][]. In such a situation, simply insert the text as you normally -would and the text will be automatically run through the Inline Patterns. +would and the text will be automatically run through the Inline Patterns. However, if you do *not* want some text to be parsed by Inline Patterns, then insert the text as an `AtomicString`. - from markdown.util import AtomicString - some_element.text = AtomicString(some_text) +```python +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 +Here's a basic example which creates an HTML table (note that the contents of the second cell (`td2`) will be run through Inline Patterns 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.util.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 +```python +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.util.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 +```python +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) +[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. +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 an `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 +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 +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 + 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` @@ -422,23 +440,25 @@ accepts two arguments: Contains all the various global variables within the markdown module. !!! Warning - With access to the above items, theoretically you have the option to - change anything through various [monkey_patching][] techniques. However, - you should be aware that the various undocumented parts of markdown may + With access to the above items, theoretically you have the option to + change anything through various [monkey_patching][] techniques. However, + you should be aware that the various undocumented 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 + 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 +```python +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. + + * A greater-than sign (`>`) 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)] +```pycon +>>> 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 +`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] +```pycon +>>> od.add('two', 2, '>one') # Insert after 'one' +>>> od.values() +[1, 2, 3, 4] +``` Now let's insert another item. - >>> od.add('two-point-five', 2.5, '>> od.keys() - ["one", "two", "two-point-five", "three", "four"] +```pycon +>>> od.add('two-point-five', 2.5, '>> od.keys() +["one", "two", "two-point-five", "three", "four"] +``` Note that we also could have set the location of "two-point-five" 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 +(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 "two-point-five" in the above examples was loaded before a separate extension which adds 'two'. You may need to take this into consideration when adding your @@ -511,30 +537,39 @@ extension components to the various markdown OrderedDicts. Once an OrderedDict is created, the items are available via key: - MyNode = od['somekey'] +```python +MyNode = od['somekey'] +``` Therefore, to delete an existing item: - del od['somekey'] +```python +del od['somekey'] +``` To change the value of an existing item (leaving location unchanged): - od['somekey'] = MyNewObject() +```python +od['somekey'] = MyNewObject() +``` To change the location of an existing item: - t.link('somekey', 'This is a paragraph.

    +```html +

    This is a paragraph.

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

    A setext style header

    -

    A hash style header

    +```html +

    A setext style header

    +

    A hash style header

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

    link

    +```html +

    link

    +``` Usage ----- diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md index 0389caffc..119f52080 100644 --- a/docs/extensions/code_hilite.md +++ b/docs/extensions/code_hilite.md @@ -32,7 +32,9 @@ The CSS rules either need to be defined in or linked from the header of your HTML templates. Pygments can generate CSS rules for you. Just run the following command from the command line: - pygmentize -S default -f html -a .codehilite > styles.css +```bash +pygmentize -S default -f html -a .codehilite > styles.css +``` If you are using a different `css_class` (default: `.codehilite`), then set the value of the `-a` option to that class name. The CSS rules will be @@ -43,7 +45,9 @@ If you would like to use a different theme, swap out `default` for the desired theme. For a list of themes installed on your system (additional themes can be installed via Pygments plugins), run the following command: - pygmentize -L style +```bash +pygmentize -L style +``` See Pygments' excellent [documentation] for more details. If no language is defined, Pygments will attempt to guess the language. When that fails, the code @@ -87,8 +91,10 @@ code block contains and each one has a different result. If the first line of the code block contains a shebang, the language is derived from that and line numbers are used. - #!/usr/bin/python - # Code goes here ... +```md + #!/usr/bin/python + # Code goes here ... +``` Will result in: @@ -101,11 +107,14 @@ 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 ... +```md + #!python + # Code goes here ... +``` Will result in: + #!python # Code goes here ... ### Colons ### @@ -114,11 +123,14 @@ 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 ... +```md + :::python + # Code goes here ... +``` Will result in: + :::python # Code goes here ... Certain lines can be selected for emphasis with the colon syntax. When @@ -139,7 +151,9 @@ CodeHilite is completely backwards compatible so that if a code block is encountered that does not define a language, the block is simply wrapped in `
    ` tags and output.
 
-        # Code goes here ...
+```md
+    # Code goes here ...
+```
 
 Will result in:
 
@@ -147,8 +161,10 @@ Will result in:
 
 Lets see the source for that:
 
-    
    # Code goes here ...
-    
    
+```html
+
    # Code goes here ...
+
    
+```
 
 !!! Note
     When no language is defined, the Pygments highlighting engine will try to guess
diff --git a/docs/extensions/definition_lists.md b/docs/extensions/definition_lists.md
index 7f72448ca..e9f898477 100644
--- a/docs/extensions/definition_lists.md
+++ b/docs/extensions/definition_lists.md
@@ -14,31 +14,34 @@ This extension is included in the standard Markdown library.
 Syntax
 ------
 
-Definition lists are defined using the syntax established in 
+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.
+```md
+Apple
+:   Pomaceous fruit of plants of the genus Malus in
+    the family Rosaceae.
 
-    Orange
-    :   The fruit of an evergreen tree of the genus Citrus.
+Orange
+:   The fruit of an evergreen tree of the genus Citrus.
+```
 
 will be rendered as:
 
-    
    
-    
    Apple
    
-    
    Pomaceous fruit of plants of the genus Malus in 
-    the family Rosaceae.
    
-
-    
    Orange
    
-    
    The fruit of an evergreen tree of the genus Citrus.
    
-    
    
+```html
+
    
+
    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
 -----
diff --git a/docs/extensions/extra.md b/docs/extensions/extra.md
index 1f33ba621..966869d1a 100644
--- a/docs/extensions/extra.md
+++ b/docs/extensions/extra.md
@@ -19,7 +19,7 @@ The supported extensions include:
 * [Tables](tables.md)
 * [Smart Strong](smart_strong.md)
 
-See each individual extension for syntax documentation. Extra and all its 
+See each individual extension for syntax documentation. Extra and all its
 supported extensions are included in the standard Markdown library.
 
 Usage
@@ -27,15 +27,17 @@ Usage
 
 From the Python interpreter:
 
-    >>> import markdown
-    >>> html = markdown.markdown(text, ['markdown.extensions.extra'])
+```pycon
+>>> import markdown
+>>> html = markdown.markdown(text, ['markdown.extensions.extra'])
+```
 
 There may be [additional extensions](index.md) 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 
+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.md)).  
 
 Markdown Inside HTML Blocks
@@ -56,15 +58,18 @@ regardless of tag. If the default is overridden by a value of `block`,
 *block parsing will occur* regardless of tag.
 
 #### Simple Example:
-```
+
+```md
 This is *true* markdown text.
 
 
    
 This is *true* markdown text.
 
    
 ```
+
 #### Result:
-```
+
+```html
 
    This is true markdown text.
    
 
    
 
    This is true markdown text.
    
@@ -80,7 +85,8 @@ unexpected results:
 * Only have one level of nesting.
 
 #### Complex Example:
-```
+
+```md
 
    
 
 The text of the `Example` element.
@@ -116,8 +122,10 @@ Raw HTML blocks may also be nested.
 
 This text is after the markdown in HTML.
 ```
+
 #### Result:
-```
+
+```html
 
    
 
    The text of the Example element.
    
 
    
diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md
index 7bfffa890..8eae42ec3 100644
--- a/docs/extensions/fenced_code_blocks.md
+++ b/docs/extensions/fenced_code_blocks.md
@@ -14,20 +14,22 @@ This extension is included in the standard Markdown library.
 Syntax
 ------
 
-Fenced Code Blocks are defined using the syntax established in 
+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:
+```md
+This is a paragraph introducing:
 
+~~~~~~~~~~~~~~~~~~~~
+a one-line code block
     ~~~~~~~~~~~~~~~~~~~~
-    a one-line code block
-    ~~~~~~~~~~~~~~~~~~~~
+```
 
-Fenced code blocks can have a blank line as the first  and/or last line of a 
+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.
 
@@ -38,40 +40,46 @@ part of the list.
 
 ### Language ###
 
-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 
+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
-    ~~~~
+```md
+~~~~{.python}
+# python code
+~~~~
 
-    ~~~~.html
-    
    HTML Document
    
-    ~~~~
+~~~~.html
+
    HTML Document
    
+~~~~
+```
 
 The above will output:
 
-    
    # python code
-    
    
-    
-    
    <p>HTML Document</p>
-    
    
+```html
+
    # python code
+
    
+
+
    <p>HTML Document</p>
+
    
+```
 
 [GitHub][]'s backtick (`\``) syntax is also supported:
 
-    ```python
-    # more python code
-    ```
+````md
+```python
+# more python code
+```
+````
 
 [GitHub]: http://github.github.com/github-flavored-markdown/
 
 ### Emphasized Lines ###
 
-If you would like to have your fenced code blocks highlighted with the 
+If you would like to have your fenced code blocks highlighted with the
 [CodeHilite][] extension, simply enable that extension (remember that
 [Pygments][] is its dependency) and the language of your fenced code blocks
 will be passed in and highlighted appropriately.
@@ -81,19 +89,23 @@ can also have emphasized certain lines of code.
 
 The lines can be specified with PHP Extra's syntax:
 
-    ~~~~{.python hl_lines="1 3"}
-    # This line is emphasized
-    # This line isn't
-    # This line is emphasized
-    ~~~~
+```md
+~~~~{.python hl_lines="1 3"}
+# This line is emphasized
+# This line isn't
+# This line is emphasized
+~~~~
+```
 
 ... or with GitHub's:
 
-    ```python hl_lines="1 3"
-    # This line is emphasized
-    # This line isn't
-    # This line is emphasized
-    ```
+````md
+```python hl_lines="1 3"
+# This line is emphasized
+# This line isn't
+# This line is emphasized
+```
+````
 
 [CodeHilite]: code_hilite.html
 [Pygments]: http://pygments.org/
diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md
index 2554bbd64..c94c2c454 100644
--- a/docs/extensions/footnotes.md
+++ b/docs/extensions/footnotes.md
@@ -14,48 +14,51 @@ This extension is included in the standard Markdown library.
 Syntax
 ------
 
-Python-Markdown's Footnote syntax follows the generally accepted syntax of the 
+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 
+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[^@#$%] and the footnote's content.
+```md
+Footnotes[^1] have a label[^@#$%] and the footnote's content.
 
-    [^1]: This is a footnote content.
-    [^@#$%]: A footnote on the label: "@#$%".
+[^1]: This is a footnote content.
+[^@#$%]: A footnote on the label: "@#$%".
+```
 
-A footnote label must start with a caret `^` and may contain any inline text 
+A footnote label must start with a caret `^` and may contain any inline text
 (including spaces) between a set of square brackets `[]`. Only the first
 caret has any special meaning.
 
-A footnote content must start with the label followed by a colon and at least 
+A footnote content must start with the label followed by a colon and at least
 one space. The label used to define the content must exactly match the label used
-in the body (including capitalization and white space). The content would then 
-follow the label either on the same line or on the next line. The content may 
-contain multiple lines, paragraphs, code blocks, blockquotes and most any other 
-markdown syntax. The additional lines must be indented one level (four spaces or 
-one tab). 
-
-When working with multiple blocks, it may be helpful to start the content on a 
-separate line from the label which defines the content. This way the entire block 
+in the body (including capitalization and white space). The content would then
+follow the label either on the same line or on the next line. The content may
+contain multiple lines, paragraphs, code blocks, blockquotes and most any other
+markdown syntax. The additional lines must be indented one level (four spaces or
+one tab).
+
+When working with multiple blocks, it may be helpful to start the content on a
+separate line from the label which defines the content. This way the entire block
 is indented consistently and any errors are more easily discernible by the author.
 
-    [^1]: 
-        The first paragraph of the definition.
+```md
+[^1]:
+    The first paragraph of the definition.
 
-        Paragraph two of the definition.
+    Paragraph two of the definition.
 
-        > A blockquote with
-        > multiple lines.
+    > A blockquote with
+    > multiple lines.
 
-            a code block
-
-        A final paragraph.
+        a code block
 
+    A final paragraph.
+```
 
 Usage
 -----
@@ -78,7 +81,7 @@ The following options are provided to configure the output:
 * **`UNIQUE_IDS`**:
     Whether to avoid collisions across multiple calls to `reset()`. Defaults to
     `False`.
-    
+
 * **`BACKLINK_TEXT`**:
     The text string that links from the footnote definition back to the position
     in the document. Defaults to `↩`.
diff --git a/docs/extensions/header_id.md b/docs/extensions/header_id.md
index 9aadf76be..63091c569 100644
--- a/docs/extensions/header_id.md
+++ b/docs/extensions/header_id.md
@@ -15,25 +15,29 @@ This extension is included in the standard Markdown library.
     This extension is **Pending Deprecation**. The [Table of Contents][toc]
     Extension should be used instead, which offers most the features of this
     extension and more.
-    
+
 [toc]: toc.md
 
 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). 
+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
+```md
+#Header
+#Header
+#Header
+```
 
 Results in:
 
-    
    Header
    
-    
    Header
    
-    
    Header
    
+```html
+
    Header
    
+
    Header
    
+
    Header
    
+```
 
 Usage
 -----
@@ -51,10 +55,11 @@ The following options are provided to configure the output:
     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 
+    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:
 
+        :::pycon
         >>>  text = '''
         ... #Some Header
         ... ## Next Level'''
@@ -68,10 +73,11 @@ The following options are provided to configure the output:
 
     Default: `True`
 
-    The `forceid` setting turns on or off the automatically generated ids for 
+    The `forceid` setting turns on or off the automatically generated ids for
     headers that do not have one explicitly defined (using the
     [Attribute List](attr_list.md) extension).
 
+        :::pycon
         >>> text = '''
         ... # Some Header
         ... # Header with ID # { #foo }'''
@@ -100,23 +106,26 @@ Using with Meta-Data
 --------------------
 
 The HeaderId extension also supports the [Meta-Data](meta_data.md) extension.
-Please see the documentation for that extension for specifics. The supported 
+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. 
+`extension_configs` interface.
 
 This document:
 
-    header_level: 2
-    header_forceid: Off
-
-    # A Header
+```md
+header_level: 2
+header_forceid: Off
 
+# A Header
+```
 
 Will result in the following output:
 
-    
    A Header
    
+```html
+
    A Header
    
+```
diff --git a/docs/extensions/index.md b/docs/extensions/index.md
index 1e05ddd07..34f80848d 100644
--- a/docs/extensions/index.md
+++ b/docs/extensions/index.md
@@ -9,13 +9,17 @@ actual source files.
 
 To use an extension, pass it to markdown with the `extensions` keyword.
 
-    markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes'])
+```python
+markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes'])
+```
 
 See the [Library Reference](../reference.md#extensions) for more details.
 
 From the command line, specify an extension with the `-x` option.
 
-    $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html
+```bash
+python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html
+```
 
 See the [Command Line docs](../cli.md) or use the `--help` option for more details.
 
diff --git a/docs/extensions/meta_data.md b/docs/extensions/meta_data.md
index b87a7751b..36d5e7acb 100644
--- a/docs/extensions/meta_data.md
+++ b/docs/extensions/meta_data.md
@@ -19,26 +19,28 @@ This extension is included in the standard Markdown library.
 Syntax
 ------
 
-Meta-data consists of a series of keywords and values defined at the beginning 
+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
+```md
+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.
+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 
+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 by 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. 
+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.
@@ -61,30 +63,32 @@ See [Extensions](index.md) for general extension usage, specify
 Accessing the Meta-Data
 -----------------------
 
-The meta-data is made available as a python Dict in the `Meta` attribute of an 
+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 = ['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 
+```pycon
+>>> md = markdown.Markdown(extensions = ['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
@@ -94,7 +98,7 @@ the developer.
 Compatible Extensions
 ---------------------
 
-The following extensions are currently known to work with the Meta-Data 
+The following extensions are currently known to work with the Meta-Data
 extension. The keywords they are known to support are also listed.
 
 * [HeaderId](header_id.md)
@@ -104,4 +108,3 @@ extension. The keywords they are known to support are also listed.
     * `wiki_base_url`
     * `wiki_end_url`
     * `wiki_html_class`
-
diff --git a/docs/extensions/nl2br.md b/docs/extensions/nl2br.md
index da419523e..04adf3638 100644
--- a/docs/extensions/nl2br.md
+++ b/docs/extensions/nl2br.md
@@ -14,15 +14,17 @@ StackOverflow and [GitHub][] flavored Markdown do.
 Example
 -------
 
-    >>> import markdown
-    >>> text = """
-    ... Line 1
-    ... Line 2
-    ... """
-    >>> html = markdown.markdown(text, extensions=['markdown.extensions.nl2br'])
-    >>> print html
-    
    Line 1
    
-    Line 2
    
+```pycon
+>>> import markdown
+>>> text = """
+... Line 1
+... Line 2
+... """
+>>> html = markdown.markdown(text, extensions=['markdown.extensions.nl2br'])
+>>> print html
+
    Line 1
    
+Line 2
    
+```
 
 Usage
 -----
diff --git a/docs/extensions/sane_lists.md b/docs/extensions/sane_lists.md
index e1a9bab83..49a7a85bf 100644
--- a/docs/extensions/sane_lists.md
+++ b/docs/extensions/sane_lists.md
@@ -18,45 +18,53 @@ 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
+```md
+1. Ordered item 1
+2. Ordered item 2
 
-    * Unordered item 1
-    * Unordered item 2
+* Unordered item 1
+* Unordered item 2
+```
 
 will result in the following output:
 
-    
      
-      
    1. Ordered item 1
      2. 
-      
    2. Ordered item 2
      3. 
-    
    
+```html
+
      
+  
    1. Ordered item 1
      2. 
+  
    2. Ordered item 2
      3. 
+
    
 
-    
      
-      
    • Unordered item 1
      • 
-      
    • Unordered item 2
      • 
-    
    
+
      
+  
    • 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. 
+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.
+```md
+A Paragraph.
+* Not a list item.
 
-    1. Ordered list item.
-    * Not a separate 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.
    
+```html
+
    A Paragraph.
+* Not a list item.
    
 
-    
      
-      
    1. Ordered list item.
-      * Not a separate list item.
      2. 
-    
    
+
      
+  
    1. Ordered list item.
+  * Not a separate list item.
      2. 
+
    
+```
 
 In all other ways, Sane Lists should behave as normal Markdown lists.
 
diff --git a/docs/extensions/smart_strong.md b/docs/extensions/smart_strong.md
index 29bd0c941..1fb3c68dc 100644
--- a/docs/extensions/smart_strong.md
+++ b/docs/extensions/smart_strong.md
@@ -12,21 +12,23 @@ underscores.
 
 The Smart_Strong extension is included in the standard Markdown library.
 
-[smart_emphasis]: ../reference.html#smart_emphasis
+[smart_emphasis]: ../reference.md#smart_emphasis
 
 Example
 -------
 
-    >>> import markdown
-    >>> markdown.markdown('Text with double__underscore__words.', \
-                          extensions=['markdown.extensions.smart_strong'])
-    u'
    Text with double__underscore__words.
    '
-    >>> markdown.markdown('__Strong__ still works.', \
-                          extensions=['markdown.extensions.smart_strong'])
-    u'
    Strong still works.
    '
-    >>> markdown.markdown('__this__works__too__.', \
-                          extensions=['markdown.extensions.smart_strong'])
-    u'
    this__works__too.
    '
+```pycon
+>>> import markdown
+>>> markdown.markdown('Text with double__underscore__words.', \
+                      extensions=['markdown.extensions.smart_strong'])
+u'
    Text with double__underscore__words.
    '
+>>> markdown.markdown('__Strong__ still works.', \
+                      extensions=['markdown.extensions.smart_strong'])
+u'
    Strong still works.
    '
+>>> markdown.markdown('__this__works__too__.', \
+                      extensions=['markdown.extensions.smart_strong'])
+u'
    this__works__too.
    '
+```
 
 Usage
 -----
diff --git a/docs/extensions/smarty.md b/docs/extensions/smarty.md
index e09aa6e17..8c0d8cc12 100644
--- a/docs/extensions/smarty.md
+++ b/docs/extensions/smarty.md
@@ -19,39 +19,41 @@ ASCII symbol | Replacements    | HTML Entities       | Substitution Keys
 `---`        | —         | `—`           | `'mdash'`
 
 Using the configuration option 'substitutions' you can overwrite the
-default substitutions. Just pass a dict mapping (a subset of) the 
+default substitutions. Just pass a dict mapping (a subset of) the
 keys to the substitution strings.
-    
-For example, one might use the following configuration to get correct quotes for 
+
+For example, one might use the following configuration to get correct quotes for
 the German language:
 
-    extension_configs = {
-        'markdown.extensions.smarty': {
-            'substitutions': {
-                'left-single-quote': '‚', # sb is not a typo!
-                'right-single-quote': '‘',
-                'left-double-quote': '„',
-                'right-double-quote': '“'
-            }
+```python
+extension_configs = {
+    'markdown.extensions.smarty': {
+        'substitutions': {
+            'left-single-quote': '‚', # sb is not a typo!
+            'right-single-quote': '‘',
+            'left-double-quote': '„',
+            'right-double-quote': '“'
         }
     }
+}
+```
 
 !!! note
-    This extension re-implements the Python [SmartyPants] 
+    This extension re-implements the Python [SmartyPants]
     library by integrating it into the markdown parser.
     While this does not provide any additional features,
-    it does offer a few advantages. Notably, it will not 
-    try to work on highlighted code blocks (using the 
-    [CodeHilite] Extension) like the third party library 
+    it does offer a few advantages. Notably, it will not
+    try to work on highlighted code blocks (using the
+    [CodeHilite] Extension) like the third party library
     has been known to do.
-    
+
 [SmartyPants]: http://pythonhosted.org/smartypants/
 [CodeHilite]: code_hilite.html
 
 Usage
 -----
 
-See [Extensions](index.md) for general extension usage, specify 
+See [Extensions](index.md) for general extension usage, specify
 `markdown.extensions.smarty` as the name of the extension.
 
 See the [Library Reference](../reference.md#extensions) for information about
diff --git a/docs/extensions/tables.md b/docs/extensions/tables.md
index 7ae10e844..2bea47078 100644
--- a/docs/extensions/tables.md
+++ b/docs/extensions/tables.md
@@ -19,31 +19,35 @@ Tables are defined using the syntax established in [PHP Markdown Extra][php].
 
 Thus, the following text (taken from the above referenced PHP documentation):
 
-    First Header  | Second Header
-    ------------- | -------------
-    Content Cell  | Content Cell
-    Content Cell  | Content Cell
+```md
+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
    
+```html
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
    First HeaderSecond Header
    Content CellContent Cell
    Content CellContent Cell
    
+```
 
 Usage
 -----
diff --git a/docs/extensions/toc.md b/docs/extensions/toc.md
index 5b356090f..98a4a1ea9 100644
--- a/docs/extensions/toc.md
+++ b/docs/extensions/toc.md
@@ -14,50 +14,60 @@ This extension is included in the standard Markdown library.
 Syntax
 ------
 
-By default, all headers will automatically have unique `id` attributes 
+By default, all headers will automatically have unique `id` attributes
 generated based upon the text of the header. Note this example, in which all
 three headers would have the same `id`:
 
-    #Header
-    #Header
-    #Header
+```md
+#Header
+#Header
+#Header
+```
 
 Results in:
 
-    
    Header
    
-    
    Header
    
-    
    Header
    
+```html
+
    Header
    
+
    Header
    
+
    Header
    
+```
 
 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]
+```md
+[TOC]
 
-    # Header 1
+# Header 1
 
-    ## Header 2
+## Header 2
+```
 
 would generate the following output:
 
-    
    
+```html
+
    
+  
    
-    
    Header 1
    
-    
    Header 2
    
+  
+
    
+
    Header 1
    
+
    Header 2
    
+```
 
 Regardless of whether a `marker` is found in the document (or disabled), the Table of
 Contents is available as an attribute (`toc`) on the Markdown class. This allows
 one to insert the Table of Contents elsewhere in their page template. For example:
 
-    >>> md = markdown.Markdown(extensions=['markdown.extensions.toc'])
-    >>> html = md.convert(text)
-    >>> page = render_some_template(context={'body': html, 'toc': md.toc})
+```pycon
+>>> md = markdown.Markdown(extensions=['markdown.extensions.toc'])
+>>> html = md.convert(text)
+>>> page = render_some_template(context={'body': html, 'toc': md.toc})
+```
 
 Usage
 -----
@@ -72,7 +82,7 @@ The following options are provided to configure the output:
 
 * **`marker`**:
     Text to find and replace with the Table of Contents. Defaults to `[TOC]`.
-    
+
     Set to an empty string to disable searching for a marker, which may save some time,
     especially on long documents.
 
@@ -85,7 +95,7 @@ The following options are provided to configure the output:
 * **`permalink`**:
     Set to `True` or a string to generate permanent links at the end of each header.
     Useful with Sphinx style sheets.
-    
+
     When set to `True` the paragraph symbol (¶ or "`¶`") is used as the link
     text. When set to a string, the provided string is used as the link text.
 
@@ -93,10 +103,11 @@ The following options are provided to configure the output:
     Base level for headers. Defaults to `1`.
 
     The `baselevel` setting allows the header levels to be automatically adjusted to
-    fit within the hierarchy of your HTML templates. For example, suppose the 
+    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:
 
+        :::pycon
         >>>  text = '''
         ... #Some Header
         ... ## Next Level'''
diff --git a/docs/extensions/wikilinks.md b/docs/extensions/wikilinks.md
index c2cd7358a..f9a8b7e32 100644
--- a/docs/extensions/wikilinks.md
+++ b/docs/extensions/wikilinks.md
@@ -19,11 +19,15 @@ Syntax
 A ``[[bracketed]]`` word is any combination of  upper or lower case letters,
 number, dashes, underscores and spaces surrounded by double brackets. Therefore
 
-    [[Bracketed]]
+```md
+[[Bracketed]]
+```
 
 would produce the following HTML:
 
-    Bracketed
+```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
@@ -33,11 +37,15 @@ 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]]
+```md
+[[Wiki Link]]
+```
 
 becomes
 
-    Wiki Link
+```html
+Wiki Link
+```
 
 Usage
 -----
@@ -73,36 +81,46 @@ The following options are provided to change the default behavior:
 For an example, let us suppose links should always point to the sub-directory
 `/wiki/` and end with `.html`
 
-    >>> from markdown.extensions.wikilinks import WikiLinkExtension
-	>>> html = markdown.markdown(text,
-    ...     extensions=[WikiLinkExtension(base_url='/wiki/', end_url='.html')]
-    ... )
+```pycon
+>>> from markdown.extensions.wikilinks import WikiLinkExtension
+>>> html = markdown.markdown(text,
+...     extensions=[WikiLinkExtension(base_url='/wiki/', end_url='.html')]
+... )
+```
 
 The above would result in the following link for `[[WikiLink]]`.
 
-    WikiLink
+```html
+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
-	...
-    >>> html = markdown.markdown(text,
-    ...     extensions=[WikiLinkExtension(build_url=my_url_builder)],
-    ... )
+```pycon
+>>> def my_url_builder(label, base, end):
+...    # do stuff
+...    return url
+...
+>>> html = markdown.markdown(text,
+...     extensions=[WikiLinkExtension(build_url=my_url_builder)],
+... )
+```
 
 The option is also provided to change or remove the class attribute.
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=[WikiLinkExtension(html_class='myclass')]
-    ... )
+```pycon
+>>> html = markdown.markdown(text,
+...     extensions=[WikiLinkExtension(html_class='myclass')]
+... )
+```
 
 Would cause all WikiLinks to be assigned to the class `myclass`.
 
-    WikiLink
+```html
+WikiLink
+```
 
 Using with Meta-Data extension
 ------------------------------
@@ -120,12 +138,16 @@ When used, the meta-data will override the settings provided through the
 
 This document:
 
-    wiki_base_url: http://example.com/
-    wiki_end_url:  .html
-    wiki_html_class:
+```md
+wiki_base_url: http://example.com/
+wiki_end_url:  .html
+wiki_html_class:
 
-    A [[WikiLink]] in the first paragraph.
+A [[WikiLink]] in the first paragraph.
+```
 
 would result in the following output (notice the blank `wiki_html_class`):
 
-    
    A WikiLink in the first paragraph.
    
+```html
+
    A WikiLink in the first paragraph.
    
+```
diff --git a/docs/index.md b/docs/index.md
index a123395fa..a9e67ec91 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -72,7 +72,7 @@ are summarized below:
     Python-Markdown defaults to ignoring middle-word emphasis. In other words,
     `some_long_filename.txt` will not become `somelongfilename.txt`.
     This can be switched off if desired. See the
-    [Library Reference](reference.html#smart_emphasis) for details.
+    [Library Reference](reference.md#smart_emphasis) for details.
 
 * __Indentation/Tab Length__
 
@@ -94,7 +94,7 @@ are summarized below:
 
 * __Consecutive Lists__
 
-    While the syntax rules are not clear on this, many implementations (including 
+    While the syntax rules are not clear on this, many implementations (including
     the original) do not end one list and start a second list when the list marker
     (asterisks, pluses, hyphens, and numbers) changes. For consistency,
     Python-Markdown maintains the same behavior with no plans to change in the
diff --git a/docs/install.md b/docs/install.md
index 783b1b130..d7997973b 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -6,21 +6,25 @@ Installing Python-Markdown
 The Easy Way
 ------------
 
-The easiest way to install Python-Markdown is simply to type one of the 
+The easiest way to install Python-Markdown is simply to type one of the
 following commands from the command line as an Admin/Root user:
 
-    pip install markdown
+```bash
+pip install markdown
+```
 
 or
 
-    easy_install markdown
+```bash
+easy_install markdown
+```
 
 That's it! You're ready to [use](reference.md) Python-Markdown. Enjoy!
 
 Installing on Windows {: #windows }
 -----------------------------------
 
-Download the Windows installer (`.exe`) from 
+Download the Windows installer (`.exe`) from
 [PyPI](http://pypi.python.org/pypi/Markdown)
 
 Double-click the file and follow the instructions.
@@ -29,12 +33,14 @@ If you prefer to manually install Python-Markdown in Windows, download the
 Zip file, unzip it, and on the command line in the directory you unzipped to,
 run the following command:
 
-    C://path/to/python.exe setup.py install
+```text
+C://path/to/python.exe setup.py install
+```
 
 If you plan to use the provided command line script, you need to make sure your
 script directory is on your system path. On a typical Python install of Windows
 the Scripts directory is `C:\PythonXX\Scripts\` (were "XX" is the Python version
-number, i.e., "27"). Adjust the path according to your system and add to your 
+number, i.e., "27"). Adjust the path according to your system and add to your
 system path.
 
 Installing on \*nix Systems {: #linux }
@@ -42,22 +48,26 @@ Installing on \*nix Systems {: #linux }
 
 From the command line do the following (where 2.x is the version number):
 
-    wget http://pypi.python.org/packages/source/M/Markdown/Markdown-2.x.tar.gz
-    tar xvzf Markdown-2.x.tar.gz
-    cd markdown-2.x/
-    sudo python setup.py install
+```bash
+wget http://pypi.python.org/packages/source/M/Markdown/Markdown-2.x.tar.gz
+tar xvzf Markdown-2.x.tar.gz
+cd markdown-2.x/
+sudo python setup.py install
+```
 
 See [PyPI](http://pypi.python.org/pypi/Markdown) for all available versions.
 
 Using the Git Repository {: #git }
 ----------------------------------
 
-If you're the type that likes to live on the edge, you may want to keep up with 
+If you're the type that likes to live on the edge, you may want to keep up with
 the latest additions and bug fixes in the repository between releases.
 Python-Markdown is maintained in a Git repository on GitHub.com. To
 get a copy of Python-Markdown from the repository do the following from the
 command line:
 
-    git clone git://github.com/Python-Markdown/markdown.git python-markdown
-    cd python-markdown
-    python setup.py install
+```bash
+git clone git://github.com/Python-Markdown/markdown.git python-markdown
+cd python-markdown
+python setup.py install
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 2e3d45960..dfecb3cea 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,8 +31,8 @@ pages:
       - Meta-Data: extensions/meta_data.md
       - New Line to Break: extensions/nl2br.md
       - Sane Lists: extensions/sane_lists.md
-      - SmartyPants: extensions/smarty.md
       - Smart Strong: extensions/smart_strong.md
+      - SmartyPants: extensions/smarty.md
       - Table of Contents: extensions/toc.md
       - Tables: extensions/tables.md
       - WikiLinks: extensions/wikilinks.md

From 61e8692794a72d9cd9932cd11baee5d2d0d1b7b3 Mon Sep 17 00:00:00 2001
From: Waylan Limberg 
Date: Wed, 6 Dec 2017 23:03:09 -0500
Subject: [PATCH 7/7] Markdown lint and other cleanup.

---
 CODE_OF_CONDUCT.md                    |   1 -
 LICENSE.md                            |  25 ++-
 README.md                             |  33 ++-
 docs/authors.md                       |  38 ++--
 docs/change_log/release-2.0.md        |  34 +--
 docs/change_log/release-2.1.md        |  69 +++---
 docs/change_log/release-2.2.md        | 128 +++++------
 docs/change_log/release-2.3.md        |  95 ++++----
 docs/change_log/release-2.4.md        |  46 ++--
 docs/change_log/release-2.5.md        | 160 +++++++-------
 docs/change_log/release-2.6.md        | 299 +++++++++++++++-----------
 docs/cli.md                           |  43 ++--
 docs/extensions/admonition.md         |   1 +
 docs/extensions/api.md                |  77 ++++---
 docs/extensions/attr_list.md          |  18 +-
 docs/extensions/code_hilite.md        |  28 +--
 docs/extensions/extra.md              |  17 +-
 docs/extensions/fenced_code_blocks.md |  16 +-
 docs/extensions/header_id.md          |   2 +-
 docs/extensions/nl2br.md              |   4 +-
 docs/extensions/toc.md                |  24 ++-
 docs/extensions/wikilinks.md          |  17 +-
 docs/index.md                         |   9 +-
 docs/reference.md                     | 155 +++++++------
 docs/test_suite.md                    |  58 ++---
 25 files changed, 735 insertions(+), 662 deletions(-)

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index e8679d623..10044e459 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -41,7 +41,6 @@ is deemed necessary and appropriate to the circumstances. Maintainers are
 obligated to maintain confidentiality with regard to the reporter of an
 incident.
 
-
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 1.3.0, available at
 [http://contributor-covenant.org/version/1/3/0/][version]
diff --git a/LICENSE.md b/LICENSE.md
index 4cd8b1455..2652d97ad 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,20 +1,20 @@
-Copyright 2007, 2008 The Python Markdown Project (v. 1.7 and later)  
-Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)  
-Copyright 2004 Manfred Stienstra (the original version)  
+Copyright 2007, 2008 The Python Markdown Project (v. 1.7 and later)
+Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
+Copyright 2004 Manfred Stienstra (the original version)
 
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
-    
-*   Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-*   Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
-*   Neither the name of the  nor the
-    names of its contributors may be used to endorse or promote products
-    derived from this software without specific prior written permission.
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+* Neither the name of the Python Markdown Project nor the
+  names of its contributors may be used to endorse or promote products
+  derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE PYTHON MARKDOWN PROJECT ''AS IS'' AND ANY
 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
@@ -27,4 +27,3 @@ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
-
diff --git a/README.md b/README.md
index 075cb05f2..33b4f71bc 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,24 @@
 [Python-Markdown][]
 ===================
 
-[![Build Status](http://img.shields.io/travis/Python-Markdown/markdown.svg)](https://travis-ci.org/Python-Markdown/markdown)
-[![Coverage Status](https://codecov.io/gh/Python-Markdown/markdown/branch/master/graph/badge.svg)](https://codecov.io/gh/Python-Markdown/markdown)
-[![Latest Version](http://img.shields.io/pypi/v/Markdown.svg)](http://pypi.python.org/pypi/Markdown)
-[![Python Versions](http://img.shields.io/pypi/pyversions/Markdown.svg)](http://pypi.python.org/pypi/Markdown)
-[![BSD License](http://img.shields.io/badge/license-BSD-yellow.svg)](http://opensource.org/licenses/BSD-3-Clause)
-[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-contributor%20covenant-green.svg?style=flat-square)][Code of Conduct]
+[![Build Status][travis-button]][travis]
+[![Coverage Status][codecov-button]][codecov]
+[![Latest Version][mdversion-button]][md-pypi]
+[![Python Versions][pyversion-button]][md-pypi]
+[![BSD License][bsdlicense-button]][bsdlicense]
+[![Code of Conduct][codeofconduct-button]][Code of Conduct]
+
+[travis-button]: http://img.shields.io/travis/Python-Markdown/markdown.svg
+[travis]: https://travis-ci.org/Python-Markdown/markdown
+[codecov-button]: https://codecov.io/gh/Python-Markdown/markdown/branch/master/graph/badge.svg
+[codecov]: https://codecov.io/gh/Python-Markdown/markdown
+[mdversion-button]: http://img.shields.io/pypi/v/Markdown.svg
+[md-pypi]: http://pypi.python.org/pypi/Markdown
+[pyversion-button]: http://img.shields.io/pypi/pyversions/Markdown.svg
+[bsdlicense-button]: http://img.shields.io/badge/license-BSD-yellow.svg
+[bsdlicense]: http://opensource.org/licenses/BSD-3-Clause
+[codeofconduct-button]: https://img.shields.io/badge/code%20of%20conduct-contributor%20covenant-green.svg?style=flat-square
+[Code of Conduct]: https://github.com/Python-Markdown/markdown/blob/master/CODE_OF_CONDUCT.md
 
 This is a Python implementation of John Gruber's [Markdown][].
 It is almost completely compliant with the reference implementation,
@@ -19,7 +31,6 @@ supported by the [Available Extensions][].
 [Features]: https://Python-Markdown.github.io#Features
 [Available Extensions]: https://Python-Markdown.github.io/extensions
 
-
 Documentation
 -------------
 
@@ -32,7 +43,8 @@ See the change log at .
 Support
 -------
 
-You may ask for help and discuss various other issues on the [mailing list][] and report bugs on the [bug tracker][].
+You may ask for help and discuss various other issues on the [mailing list][]
+and report bugs on the [bug tracker][].
 
 [mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss
 [bug tracker]: http://github.com/Python-Markdown/markdown/issues
@@ -40,6 +52,5 @@ You may ask for help and discuss various other issues on the [mailing list][] an
 Code of Conduct
 ---------------
 
-Everyone interacting in the Python-Markdown project's codebases, issue trackers, and mailing lists is expected to follow the [Code of Conduct].
-
-[Code of Conduct]: https://github.com/Python-Markdown/markdown/blob/master/CODE_OF_CONDUCT.md
+Everyone interacting in the Python-Markdown project's codebases, issue trackers,
+and mailing lists is expected to follow the [Code of Conduct].
diff --git a/docs/authors.md b/docs/authors.md
index 9b75b23cb..658707d8e 100644
--- a/docs/authors.md
+++ b/docs/authors.md
@@ -1,34 +1,34 @@
-title:      Authors
+title: Authors
 
 Primary Authors
 ===============
 
-*   __[Waylan Limberg](http://achinghead.com/)__
+* __[Waylan Limberg](http://achinghead.com/)__
 
-    Waylan is the current maintainer of the code and has written much of the current 
-    code base, included a complete refactor of the core.  He started out by 
-    authoring many of the available extensions and later was asked to join Yuri, 
-    where he began fixing numerous bugs, adding documentation and making general 
-    improvements to the existing code base.
+    Waylan is the current maintainer of the code and has written much of the
+    current code base, included a complete refactor of the core. He started out
+    by authoring many of the available extensions and later was asked to join
+    Yuri, where he began fixing numerous bugs, adding documentation and making
+    general improvements to the existing code base.
 
+* __[Yuri Takteyev](http://freewisdom.org/)__
 
-*   __[Yuri Takteyev](http://freewisdom.org/)__
+    Yuri wrote most of the code found in version 1.x while procrastinating his
+    Ph.D. Various pieces of his code still exist, most notably the basic
+    structure.
 
-    Yuri wrote most of the code found in version 1.x while procrastinating his Ph.D.
-    Various pieces of his code still exist, most notably the basic structure.
+* __[Manfed Stienstra](http://www.dwerg.net/)__
 
-*   __[Manfed Stienstra](http://www.dwerg.net/)__
-
-    Manfed wrote the original version of the script and is responsible for 
+    Manfed wrote the original version of the script and is responsible for
     various parts of the existing code base.
 
-*   __Artem Yunusov__
+* __Artem Yunusov__
 
-    Artem, who as part of a 2008 GSoC project, refactored inline patterns, 
-    replaced the NanoDOM with ElementTree support and made various other 
+    Artem, who as part of a 2008 GSoC project, refactored inline patterns,
+    replaced the NanoDOM with ElementTree support and made various other
     improvements.
 
-*   __David Wolever__
+* __David Wolever__
 
     David refactored the extension API and made other improvements
     as he helped to integrate Markdown into Dr.Project.
@@ -36,8 +36,8 @@ Primary Authors
 Other Contributors
 ==================
 
-The incomplete list of individuals below have provided patches or otherwise 
-contributed to the project in various ways. We would like to thank everyone 
+The incomplete list of individuals below have provided patches or otherwise
+contributed to the project in various ways. We would like to thank everyone
 who has contributed to the project in any way.
 
 * Eric Abrahamsen
diff --git a/docs/change_log/release-2.0.md b/docs/change_log/release-2.0.md
index 78518b887..abd8d2973 100644
--- a/docs/change_log/release-2.0.md
+++ b/docs/change_log/release-2.0.md
@@ -1,36 +1,36 @@
-title:      Release Notes for v2.0
+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 
+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 
+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. 
+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. 
+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 
+* 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, 
+* 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
@@ -41,20 +41,20 @@ 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 
+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 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 
+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 
+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
diff --git a/docs/change_log/release-2.1.md b/docs/change_log/release-2.1.md
index a48162d9b..30cf0b253 100644
--- a/docs/change_log/release-2.1.md
+++ b/docs/change_log/release-2.1.md
@@ -1,4 +1,4 @@
-title:      Release Notes for v2.1
+title: Release Notes for v2.1
 
 Python-Markdown 2.1 Release Notes
 =================================
@@ -20,45 +20,46 @@ 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.
+  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).
+  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](../extensions/header_id.md) extension
-to define custom ids on headers, you will want to switch to using the new
-[Attribute List](../extensions/attr_list.md) extension. The HeaderId extension
-now only auto-generates ids on headers which have not already had ids defined.
-Note that the [Extra](../extensions/extra.md) 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.
+  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](../extensions/header_id.md) extension to
+  define custom ids on headers, you will want to switch to using the new
+  [Attribute List](../extensions/attr_list.md) extension. The HeaderId extension
+  now only auto-generates ids on headers which have not already had ids defined.
+  Note that the [Extra](../extensions/extra.md) 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.
+  (`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
 ---------------------------------
diff --git a/docs/change_log/release-2.2.md b/docs/change_log/release-2.2.md
index 1f2a68bc0..379a43e31 100644
--- a/docs/change_log/release-2.2.md
+++ b/docs/change_log/release-2.2.md
@@ -1,64 +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 `` and `` 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
-. The docs are now maintained in the
-Repository and are generated by the `setup.py build_docs` command.
-
-The [Sane_Lists](../extensions/sane_lists.md)
-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/Python-Markdown/markdown/commits/master)
-for a complete history of the changes.
+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 `` and `` 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
+. The docs are now maintained in the
+Repository and are generated by the `setup.py build_docs` command.
+
+The [Sane_Lists](../extensions/sane_lists.md)
+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/Python-Markdown/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
index b9859483c..fc1809ee6 100644
--- a/docs/change_log/release-2.3.md
+++ b/docs/change_log/release-2.3.md
@@ -1,4 +1,4 @@
-title:      Release Notes for v2.3
+title: Release Notes for v2.3
 
 Python-Markdown 2.3 Release Notes
 =================================
@@ -14,71 +14,72 @@ 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.
+  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.
+* 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.
+* "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.
+  (`:`) 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.
+  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.
 
 [CodeHilite Extension]: ../extensions/code_hilite.md
 
 * 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={...})`).
+  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 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.
+  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.
 
 [Admonition Extension]: ../extensions/admonition.md
 [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/Python-Markdown/markdown/commits/master)
-for a complete history of the changes.
+* Various bug fixes have been made. See the [commit
+  log](https://github.com/Python-Markdown/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
index 3eb046016..19130f18f 100644
--- a/docs/change_log/release-2.4.md
+++ b/docs/change_log/release-2.4.md
@@ -12,50 +12,50 @@ 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.
+  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.
 
 [CodeHilite Extension]: ../extensions/code_hilite.md
 
 * 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.
+  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.
+  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
 [Smarty Extension]: ../extensions/smarty.md
 [SmartyPants]: http://daringfireball.net/projects/smartypants/
 
-* The [Table of Contents Extension] now supports new `permalink` option
-for creating [Sphinx]-style anchor links.
+* The [Table of Contents Extension] now supports new `permalink` option for
+  creating [Sphinx]-style anchor links.
 
 [Table of Contents Extension]: ../extensions/toc.md
 [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.
+  appending `markdown=1` to opening tag attributes. See [Markdown Inside HTML
+  Blocks] section for details. Thanks to [ryneeverett] for implementing this
+  feature.
 
 [Markdown Inside HTML Blocks]: ../extensions/extra.md#nested-markdown-inside-html-blocks
 [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]):
+  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.
@@ -68,6 +68,6 @@ the [Fenced Code Extension]):
 [Fenced Code Extension]: ../extensions/fenced_code_blocks.md
 [A. Jesse Jiryu Davis]: https://github.com/ajdavis
 
-* Various bug fixes have been made.  See the
-[commit log](https://github.com/Python-Markdown/markdown/commits/master)
-for a complete history of the changes.
+* Various bug fixes have been made. See the [commit
+  log](https://github.com/Python-Markdown/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
index 06ffeaf5e..f6a4e3661 100644
--- a/docs/change_log/release-2.5.md
+++ b/docs/change_log/release-2.5.md
@@ -24,36 +24,39 @@ Backwards-incompatible Changes
 [CodeHilite Extension]: ../extensions/code_hilite.md
 [linenums]: ../extensions/code_hilite.md#usage
 
-* 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.
+* 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)
+        html = markdown.markdown(text, same_mode=True)
 
-	Then it is recommended that you change your code to read something like this:
+    Then it is recommended that you change your code to read something like this:
 
-	    import bleach
+        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:
+    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
+        from markdown.extensions import Extension
 
-		class EscapeHtml(Extension):
-			def extendMarkdown(self, md, md_globals):
-				del md.preprocessors['html_block']
-				del md.inlinePatterns['html']
+        class EscapeHtml(Extension):
+            def extendMarkdown(self, md, md_globals):
+                del md.preprocessors['html_block']
+                del md.inlinePatterns['html']
 
-		html = markdown.markdown(text, extensions=[EscapeHtml()])
+        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"`.
+    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]: https://bleach.readthedocs.io/
 
@@ -64,29 +67,30 @@ Backwards-incompatible Changes
 
          html = markdown.markdown(text, ['extra'])
 
-	Then it is recommended that you change it to read something like this:
+    Then it is recommended that you change it to read something like this:
 
-	    html = markdown.markdown(text, extensions=['extra'])
+        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.
+    !!! 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:
+  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'])
+        markdown.markdown(text, extensions=['markdown.extensions.extra'])
 
     The same applies to the command line:
 
@@ -105,79 +109,81 @@ Backwards-incompatible Changes
 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.
+* 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.
 
 [Smarty Extension]: ../extensions/smarty.md
 [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.
+* 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.
+    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:
+    Therefore, if you were to import the class like this:
 
-		from path.to.module import SomeExtensionClass
+        from path.to.module import SomeExtensionClass
 
-	Then the named extension would comprise this string:
+    Then the named extension would comprise this string:
 
-		"path.to.module:SomeExtensionClass"
+        "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 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.
+    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.
+* 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.
+    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.
+* 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][ae] is no longer considered "experimental."
+* The [Admonition Extension][ae] is no longer considered "experimental."
 
 [ae]: ../extensions/admonition.md
 
-*   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.
+* 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/Python-Markdown/markdown/commits/master)
-    for a complete history of the changes.
+* Various bug fixes have been made. See the [commit
+  log](https://github.com/Python-Markdown/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
index 7e7f82f0e..149507215 100644
--- a/docs/change_log/release-2.6.md
+++ b/docs/change_log/release-2.6.md
@@ -1,72 +1,88 @@
-title:      Release Notes for v2.6
+title: Release Notes for v2.6
 
-Python-Markdown 2.6 Release Notes
-=================================
+# 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.
+Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as
+well as PyPy.
 
-Backwards-incompatible Changes
-------------------------------
+## 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.
+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 the next
+release. 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. In fact, [Bleach Whitelist] provides a curated
+list of tags, attributes, and styles suitable for filtering user-provided HTML
+using bleach.
 
 If your code previously looked like this:
 
-    html = markdown.markdown(text, safe_mode=True)
+```python
+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))
+```python
+import bleach
+from bleach_whitelist import markdown_tags, markdown_attrs
+html = bleach.clean(markdown.markdown(text), markdown_tags, markdown_attrs)
+```
 
-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:
+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
+```python
+from markdown.extensions import Extension
 
-    class EscapeHtml(Extension):
-        def extendMarkdown(self, md, md_globals):
-        del md.preprocessors['html_block']
-        del md.inlinePatterns['html']
+class EscapeHtml(Extension):
+    def extendMarkdown(self, md, md_globals):
+    del md.preprocessors['html_block']
+    del md.inlinePatterns['html']
 
-    html = markdown.markdown(text, extensions=[EscapeHtml()])
+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"`.
+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]: https://bleach.readthedocs.io/
+[Bleach Whitelist]: https://github.com/yourcelf/bleach-whitelist
 
 ### 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:
+Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an
+error in the next release. Only keyword arguments should be used. For example,
+if your code previously looked like this:
 
-    html = markdown.markdown(text, [SomeExtension()])
+```python
+html = markdown.markdown(text, [SomeExtension()])
+```
 
 Then it is recommended that you change it to read something like this:
 
-    html = markdown.markdown(text, extensions=[SomeExtension()])
+```python
+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.
+    position. It is recommended that you always use keywords when they are
+    supported for this reason.
 
 ### "Shortened" Extension Names Deprecated
 
@@ -74,51 +90,63 @@ 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:
+**`DeprecationWarning`** in version 2.6 and an error in the next release. Ensure
+that you always use the full path to your extensions. For example, if you
+previously did the following:
 
-    markdown.markdown(text, extensions=['extra'])
+```python
+markdown.markdown(text, extensions=['extra'])
+```
 
 You should change your code to the following:
 
-    markdown.markdown(text, extensions=['markdown.extensions.extra'])
+```python
+markdown.markdown(text, extensions=['markdown.extensions.extra'])
+```
 
 The same applies to the command line:
 
-    $ python -m markdown -x markdown.extensions.extra input.txt
+```python
+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:
+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'])
+```python
+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):
+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'])
+```python
+markdown.markdown(text, extensions=['mdx_math'])
+```
 
-Extension authors will want to update their documentation to reflect the new behavior.
+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.
+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][hid] 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][TOC] Extension instead, which offers most of the
-features of the HeaderId Extension and more (support for meta data is missing).
+**`PendingDeprecationWarning`** in version 2.6. The extension will be deprecated
+in the next release and raise an error in the release after that. Use the [Table
+of Contents][TOC] 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
@@ -129,119 +157,138 @@ 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:
+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'})
+```python
+ext = SomeExtension(configs={'somekey': 'somevalue'})
+```
 
 That code should be updated to pass in the options directly:
 
-    ext = SomeExtension(somekey='somevalue')
+```python
+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:
+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)
+```python
+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.
+```python
+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:
+
+```python
+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
----------------------------------
+## 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.
+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.
+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.
 
-Alternatively, if the `yaml` option is set, then the data is parsed as YAML.
-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
+Alternatively, if the `yaml` option is set, then the data is parsed as
+YAML. As the `yaml` option was buggy, it was removed in 2.6.1. It is
+suggested that a preprocessor (like [docdata]) or a third party extension be
+used if you want true YAML support. See [Issue #390][#390] for a full
 explanation.
 
 [MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
 [Meta-Data]: ../extensions/meta_data.md
 [YAML]: http://yaml.org/
 [#390]: https://github.com/Python-Markdown/markdown/issues/390
+[docdata]: https://github.com/waylan/docdata
 
 ### Table of Contents Extension Refactored
 
 The [Table of Contents][TOC] Extension has been refactored and some new features
-have been added.  See the documentation for a full explanation of each feature
+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 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).
+* 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.
+* 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 `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.
+* 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.
 
 [TOC]: ../extensions/toc.md
 
 ### Pygments can now be disabled
 
-The [CodeHilite][ch] 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
-`` 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.
+The [CodeHilite][ch] 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 `` 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.
 
 [ch]: ../extensions/code_hilite.md
 [spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
diff --git a/docs/cli.md b/docs/cli.md
index 9fe8a3a9a..dbac2c4fd 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -82,13 +82,14 @@ path.
     more convenient to have `markdown_py` on your path.
 
 !!!Note
-    Python-Markdown uses `"markdown_py"` as a script name because
-    the Perl implementation has already taken the more obvious name "markdown".
+    Python-Markdown uses `"markdown_py"` as a script name because the Perl
+    implementation has already taken the more obvious name "markdown".
     Additionally, the default Python configuration on some systems would cause a
-    script named `"markdown.py"` to fail by importing itself rather than the markdown
-    library. Therefore, the script has been named `"markdown_py"` as a compromise. If
-    you prefer a different name for the script on your system, it is suggested that
-    you create a symbolic link to `markdown_py` with your preferred name.
+    script named `"markdown.py"` to fail by importing itself rather than the
+    markdown library. Therefore, the script has been named `"markdown_py"` as a
+    compromise. If you prefer a different name for the script on your system, it
+    is suggested that you create a symbolic link to `markdown_py` with your
+    preferred name.
 
 Usage
 -----
@@ -137,29 +138,31 @@ can pass them in as well:
 python -m markdown -x markdown.extensions.footnotes -c config.yml input.txt
 ```
 
-The `-c` (or `--extension_configs`) option accepts a file name. The file must be in
-either the [YAML] or [JSON] format and contain YAML or JSON data that would map to
-a Python Dictionary in the format required by the [`extension_configs`][ec] keyword
-of the `markdown.Markdown` class. Therefore, the file `config.yaml` referenced in the
-above example might look like this:
+The `-c` (or `--extension_configs`) option accepts a file name. The file must be
+in either the [YAML] or [JSON] format and contain YAML or JSON data that would
+map to a Python Dictionary in the format required by the
+[`extension_configs`][ec] keyword of the `markdown.Markdown` class. Therefore,
+the file `config.yaml` referenced in the above example might look like this:
 
 ```yaml
 markdown.extensions.footnotes:
     PLACE_MARKER: ~~~~~~~~
     UNIQUE_IDS: True
 ```
-Note that while the `--extension_configs` option does specify the "markdown.extensions.footnotes"
-extension, you still need to load the extension with the `-x` option, or the configuration for that
-extension will be ignored.
 
-The `--extension_configs` option will only support YAML configuration files if [PyYAML] is
-installed on your system. JSON should work with no additional dependencies. The format
-of your configuration file is automatically detected.
+Note that while the `--extension_configs` option does specify the
+"markdown.extensions.footnotes" extension, you still need to load the extension
+with the `-x` option, or the configuration for that extension will be ignored.
+
+The `--extension_configs` option will only support YAML configuration files if
+[PyYAML] is installed on your system. JSON should work with no additional
+dependencies. The format of your configuration file is automatically detected.
 
 !!!warning
-	The previously documented method of appending the extension configuration options as a string to the
-	extension name will be deprecated in Python-Markdown version 2.6. The `--extension_configs`
-	option should be used instead. See the [2.5 release notes] for more information.
+    The previously documented method of appending the extension configuration
+    options as a string to the extension name will be deprecated in
+    Python-Markdown version 2.6. The `--extension_configs` option should be used
+    instead. See the [2.5 release notes] for more information.
 
 [ec]: reference.html#extension_configs
 [YAML]: http://yaml.org/
diff --git a/docs/extensions/admonition.md b/docs/extensions/admonition.md
index 3e0446de6..26e629963 100644
--- a/docs/extensions/admonition.md
+++ b/docs/extensions/admonition.md
@@ -40,6 +40,7 @@ will render:
 
    You should note that the title will be automatically capitalized.
    
 
    
 ```
+
 Optionally, you can use custom titles. For instance:
 
 ```md
diff --git a/docs/extensions/api.md b/docs/extensions/api.md
index bcada342c..3d8cfff46 100644
--- a/docs/extensions/api.md
+++ b/docs/extensions/api.md
@@ -1,7 +1,6 @@
 title:      Extensions API
 
-Writing Extensions for Python-Markdown
-======================================
+# 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
@@ -18,8 +17,7 @@ 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 {: #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
@@ -48,8 +46,7 @@ class MyPreprocessor(Preprocessor):
         return new_lines
 ```
 
-Inline Patterns {: #inlinepatterns }
-------------------------------------
+## 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
@@ -113,7 +110,7 @@ implemented with separate instances of the `SimpleTagPattern` listed below.
 Feel free to use or extend any of the Pattern classes found at
 `markdown.inlinepatterns`.
 
-**Generic Pattern Classes**
+### Generic Pattern Classes
 
 * **`SimpleTextPattern(pattern)`**:
 
@@ -133,8 +130,7 @@ 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 {: #treeprocessors }
 
 Treeprocessors manipulate an ElementTree object after it has passed through the
 core BlockParser. This is where additional manipulation of the tree takes
@@ -170,8 +166,7 @@ the `run` method would only return `None` or a new ElementTree object.
 For specifics on manipulating the ElementTree, see
 [Working with the ElementTree][workingwithetree] below.
 
-Postprocessors {: #postprocessors }
------------------------------------
+## Postprocessors {: #postprocessors }
 
 Postprocessors manipulate the document after the ElementTree has been
 serialized into a string. Postprocessors should be used to work with the
@@ -193,8 +188,7 @@ class TocPostprocessor(Postprocessor):
         return MYMARKERRE.sub(MyToc, text)
 ```
 
-BlockParser {: #blockparser }
------------------------------
+## BlockParser {: #blockparser }
 
 Sometimes, Preprocessors, Treeprocessors, Postprocessors, and Inline Patterns
 are not going to do what you need. Perhaps you want a new type of block type
@@ -321,8 +315,7 @@ 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 }
---------------------------------------------------
+## Working with the ElementTree {: #working_with_et }
 
 As mentioned, the Markdown parser converts a source document to an
 [ElementTree][ElementTree] object before serializing that back to Unicode text.
@@ -374,8 +367,8 @@ adds a `class` attribute to `` elements:
 
 ```python
 def set_link_class(self, element):
-	for child in element:
-	    if child.tag == "a":
+    for child in element:
+        if child.tag == "a":
               child.set("class", "myclass") #set the class attribute
           set_link_class(child) # run recursively on children
 ```
@@ -384,8 +377,7 @@ 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 }
--------------------------------------------------------------------
+## 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.
@@ -558,6 +550,7 @@ To change the location of an existing item:
 ```python
 t.link('somekey', 'A hash style header
 ```
 
-### Inline ###
+### Inline
 
 To define attributes on inline elements, the attribute list should be defined
 immediately after the inline element with no white space.
@@ -93,8 +90,7 @@ The above results in the following output:
 
    link
    
 ```
 
-Usage
------
+## Usage
 
 See [Extensions](index.md) for general extension usage, specify
 `markdown.extensions.attr_list` as the name of the extension.
diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md
index 119f52080..6490dcc57 100644
--- a/docs/extensions/code_hilite.md
+++ b/docs/extensions/code_hilite.md
@@ -1,10 +1,8 @@
 title: CodeHilite Extension
 
-CodeHilite
-==========
+# CodeHilite
 
-Summary
--------
+## Summary
 
 The CodeHilite extension adds code/syntax highlighting to standard
 Python-Markdown code blocks using [Pygments][].
@@ -13,10 +11,9 @@ Python-Markdown code blocks using [Pygments][].
 
 This extension is included in the standard Markdown library.
 
-Setup
------
+## Setup
 
-### Step 1: Download and Install Pygments ###
+### Step 1: Download and Install Pygments
 
 You will also need to [download][dl] and install the Pygments package on your
 `PYTHONPATH`. The CodeHilite extension will produce HTML output without
@@ -25,7 +22,7 @@ Pygments, but it won't highlight anything (same behavior as setting
 
 [dl]: http://pygments.org/download/
 
-### Step 2: Add CSS Classes ###
+### Step 2: Add CSS Classes
 
 You will need to define the appropriate CSS classes with appropriate rules.
 The CSS rules either need to be defined in or linked from the header of your
@@ -68,9 +65,7 @@ block will not be highlighted.
 [preview]: http://richleland.github.io/pygments-css/
 [documentation]: http://pygments.org/docs/
 
-
-Syntax
-------
+## Syntax
 
 The CodeHilite extension follows the same [syntax][] as regular Markdown code
 blocks, with one exception. The highlighter needs to know what language to use for
@@ -86,7 +81,7 @@ code block contains and each one has a different result.
 
 [syntax]: http://daringfireball.net/projects/markdown/syntax#precode
 
-### Shebang (with path) ###
+### Shebang (with path)
 
 If the first line of the code block contains a shebang, the language is derived
 from that and line numbers are used.
@@ -101,7 +96,7 @@ Will result in:
     #!/usr/bin/python
     # Code goes here ...
 
-### Shebang (no path) ###
+### 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
@@ -117,7 +112,7 @@ Will result in:
     #!python
     # Code goes here ...
 
-### Colons ###
+### 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
@@ -145,7 +140,7 @@ This is useful to direct the reader's attention to specific lines.
 !!! Note
     `hl_lines` is named for Pygments' option meaning "highlighted lines".
 
-### When No Language is Defined ###
+### When No Language is Defined
 
 CodeHilite is completely backwards compatible so that if a code block is
 encountered that does not define a language, the block is simply wrapped in
@@ -171,8 +166,7 @@ Lets see the source for that:
     the language (unless `guess_lang` is set to `False`). Upon failure, the same
     behavior will happen as described above.
 
-Usage
------
+## Usage
 
 See [Extensions](index.md) for general extension usage, specify
 `markdown.extensions.codehilite` as the name of the extension.
diff --git a/docs/extensions/extra.md b/docs/extensions/extra.md
index 966869d1a..0639d3d6d 100644
--- a/docs/extensions/extra.md
+++ b/docs/extensions/extra.md
@@ -1,10 +1,8 @@
 title: Extra Extension
 
-Python-Markdown Extra
-=====================
+# Python-Markdown Extra
 
-Summary
--------
+## Summary
 
 A compilation of various Python-Markdown extensions that (mostly) imitates
 [PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/).
@@ -22,8 +20,7 @@ The supported extensions include:
 See each individual extension for syntax documentation. Extra and all its
 supported extensions are included in the standard Markdown library.
 
-Usage
------
+## Usage
 
 From the Python interpreter:
 
@@ -38,10 +35,9 @@ 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.md)).  
+(see the [Extension API](api.md)).
 
-Markdown Inside HTML Blocks
----------------------------
+### Markdown Inside HTML Blocks
 
 Unlike the other Extra features, this feature is built into the markdown core and
 is turned on when `markdown.extensions.extra` is enabled.
@@ -77,6 +73,7 @@ This is *true* markdown text.
 ```
 
 ### Nested Markdown Inside HTML Blocks
+
 Nested elements are more sensitive and must be used cautiously. To avoid
 unexpected results:
 
@@ -123,7 +120,7 @@ Raw HTML blocks may also be nested.
 This text is after the markdown in HTML.
 ```
 
-#### Result:
+#### Complex Result:
 
 ```html
 
    
diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md
index 8eae42ec3..b7a657e42 100644
--- a/docs/extensions/fenced_code_blocks.md
+++ b/docs/extensions/fenced_code_blocks.md
@@ -1,18 +1,15 @@
 title: Fenced Code Blocks Extension
 
-Fenced Code Blocks
-==================
+# Fenced Code Blocks
 
-Summary
--------
+## Summary
 
 The Fenced Code Blocks 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
-------
+## Syntax
 
 Fenced Code Blocks are defined using the syntax established in
 [PHP Markdown Extra][php].
@@ -38,7 +35,7 @@ part of the list.
     Fenced Code Blocks are only supported at the document root level.
     Therefore, they cannot be nested inside lists or blockquotes.
 
-### Language ###
+### Language
 
 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
@@ -77,7 +74,7 @@ The above will output:
 
 [GitHub]: http://github.github.com/github-flavored-markdown/
 
-### Emphasized Lines ###
+### Emphasized Lines
 
 If you would like to have your fenced code blocks highlighted with the
 [CodeHilite][] extension, simply enable that extension (remember that
@@ -111,8 +108,7 @@ The lines can be specified with PHP Extra's syntax:
 [Pygments]: http://pygments.org/
 [colon]: code_hilite.html#colons
 
-Usage
------
+## Usage
 
 See [Extensions](index.md) for general extension usage, specify
 `markdown.extensions.fenced_code` as the name of the extension.
diff --git a/docs/extensions/header_id.md b/docs/extensions/header_id.md
index 63091c569..82e8e2cd1 100644
--- a/docs/extensions/header_id.md
+++ b/docs/extensions/header_id.md
@@ -112,7 +112,7 @@ meta-data keywords are:
 * `header_level`
 * `header_forceid`
 
-When used, the meta-data will override the settings provided through the  
+When used, the meta-data will override the settings provided through the
 `extension_configs` interface.
 
 This document:
diff --git a/docs/extensions/nl2br.md b/docs/extensions/nl2br.md
index 04adf3638..4f5e611d9 100644
--- a/docs/extensions/nl2br.md
+++ b/docs/extensions/nl2br.md
@@ -6,8 +6,8 @@ New-Line-to-Break Extension
 Summary
 -------
 
-The New-Line-to-Break (`nl2b`) Extension will cause newlines to be treated as hard breaks; like
-StackOverflow and [GitHub][] flavored Markdown do.
+The New-Line-to-Break (`nl2b`) Extension will cause newlines to be treated as
+hard breaks; like StackOverflow and [GitHub][] flavored Markdown do.
 
 [Github]: http://github.github.com/github-flavored-markdown/
 
diff --git a/docs/extensions/toc.md b/docs/extensions/toc.md
index 98a4a1ea9..a1c583f18 100644
--- a/docs/extensions/toc.md
+++ b/docs/extensions/toc.md
@@ -59,9 +59,10 @@ would generate the following output:
 
    Header 2
    
 ```
 
-Regardless of whether a `marker` is found in the document (or disabled), the Table of
-Contents is available as an attribute (`toc`) on the Markdown class. This allows
-one to insert the Table of Contents elsewhere in their page template. For example:
+Regardless of whether a `marker` is found in the document (or disabled), the
+Table of Contents is available as an attribute (`toc`) on the Markdown class.
+This allows one to insert the Table of Contents elsewhere in their page
+template. For example:
 
 ```pycon
 >>> md = markdown.Markdown(extensions=['markdown.extensions.toc'])
@@ -83,8 +84,8 @@ The following options are provided to configure the output:
 * **`marker`**:
     Text to find and replace with the Table of Contents. Defaults to `[TOC]`.
 
-    Set to an empty string to disable searching for a marker, which may save some time,
-    especially on long documents.
+    Set to an empty string to disable searching for a marker, which may save
+    some time, especially on long documents.
 
 * **`title`**:
     Title to insert in the Table of Contents' `
    `. Defaults to `None`.
@@ -96,16 +97,17 @@ The following options are provided to configure the output:
     Set to `True` or a string to generate permanent links at the end of each header.
     Useful with Sphinx style sheets.
 
-    When set to `True` the paragraph symbol (¶ or "`¶`") is used as the link
-    text. When set to a string, the provided string is used as the link text.
+    When set to `True` the paragraph symbol (¶ or "`¶`") is used as
+    the link text. When set to a string, the provided string is used as the link
+    text.
 
 * **`baselevel`**:
     Base level for headers. Defaults to `1`.
 
-    The `baselevel` setting allows the header levels to be automatically adjusted 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:
+    The `baselevel` setting allows the header levels to be automatically
+    adjusted 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:
 
         :::pycon
         >>>  text = '''
diff --git a/docs/extensions/wikilinks.md b/docs/extensions/wikilinks.md
index f9a8b7e32..a46265a5c 100644
--- a/docs/extensions/wikilinks.md
+++ b/docs/extensions/wikilinks.md
@@ -1,10 +1,8 @@
 title: WikiLinks Extension
 
-WikiLinks
-=========
+# WikiLinks
 
-Summary
--------
+## Summary
 
 The WikiLinks extension adds support for [WikiLinks][]. Specifically, any
 ``[[bracketed]]`` word is converted to a link.
@@ -13,8 +11,7 @@ This extension is included in the standard Markdown library.
 
 [WikiLinks]: http://en.wikipedia.org/wiki/Wikilink
 
-Syntax
-------
+## Syntax
 
 A ``[[bracketed]]`` word is any combination of  upper or lower case letters,
 number, dashes, underscores and spaces surrounded by double brackets. Therefore
@@ -47,8 +44,7 @@ becomes
 Wiki Link
 ```
 
-Usage
------
+## Usage
 
 See [Extensions](index.md) for general extension usage, specify
 `markdown.extensions.wikilinks` as the name of the extension.
@@ -76,7 +72,7 @@ The following options are provided to change the default behavior:
 
 * **`build_url`**: Callable which formats the URL from its parts.
 
-### Examples ###
+### Examples
 
 For an example, let us suppose links should always point to the sub-directory
 `/wiki/` and end with `.html`
@@ -122,8 +118,7 @@ Would cause all WikiLinks to be assigned to the class `myclass`.
 WikiLink
 ```
 
-Using with Meta-Data extension
-------------------------------
+## Using with Meta-Data extension
 
 The WikiLink extension also supports the [Meta-Data](meta_data.md) extension.
 Please see the documentation for that extension for specifics. The supported
diff --git a/docs/index.md b/docs/index.md
index a9e67ec91..d21b5c5aa 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -21,8 +21,8 @@ The Python-Markdown project is developed with the following goals in mind:
   suited to use in web server environments (never raise an exception, never
   write to stdout, etc.) as an implementation of the markdown parser that
   follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax)
-  and the behavior of the original (markdown.pl) implementation as reasonably
-  as possible (see [differences](#differences) for a few exceptions).
+  and the behavior of the original (markdown.pl) implementation as reasonably as
+  possible (see [differences](#differences) for a few exceptions).
 
 * Provide an [Extension API](extensions/api.md) which makes it possible
   to change and/or extend the behavior of the parser.
@@ -48,8 +48,8 @@ features:
 
 * __Output Formats__
 
-    Python-Markdown can output documents with either HTML or XHTML styel tags. See the
-    [Library Reference](reference.md#output_format) for details.
+    Python-Markdown can output documents with either HTML or XHTML styel tags.
+    See the [Library Reference](reference.md#output_format) for details.
 
 * __Command Line Interface__
 
@@ -101,7 +101,6 @@ are summarized below:
     foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.md)
     is available to provide a less surprising behavior.
 
-
 Support
 -------
 
diff --git a/docs/reference.md b/docs/reference.md
index 424ba1a94..7e5a30a98 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -1,26 +1,20 @@
-title:      Library Reference
-prev_title: Installation
-prev_url:   install.html
-next_title: Command Line
-next_url:   cli.html
+title: Library Reference
 
-
-Using Markdown as a Python Library
-==================================
+# Using Markdown as a Python Library
 
 First and foremost, Python-Markdown is intended to be a python library module
 used by various projects to convert Markdown syntax into HTML.
 
-The Basics
-----------
+## The Basics
 
 To use markdown as a module:
 
-    import markdown
-    html = markdown.markdown(your_text_string)
+```python
+import markdown
+html = markdown.markdown(your_text_string)
+```
 
-The Details
------------
+## The Details
 
 Python-Markdown provides two public functions ([`markdown.markdown`](#markdown)
 and [`markdown.markdownFromFile`](#markdownFromFile)) both of which wrap the
@@ -45,12 +39,14 @@ __text__{: #text }
         Do not pass encoded strings to it! If your input is encoded, (e.g. as
         UTF-8), it is your responsibility to decode it.  For example:
 
+            :::python
             input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
             text = input_file.read()
             html = markdown.markdown(text)
 
         If you want to write the output to disk, you *must* encode it yourself:
 
+            :::python
             output_file = codecs.open("some_file.html", "w",
                                       encoding="utf-8",
                                       errors="xmlcharrefreplace"
@@ -70,18 +66,20 @@ __extensions__{: #extensions }
     The list of extensions may contain instances of extensions and/or strings
     of extension names.
 
+        :::python
         extensions=[MyExtension(), 'path.to.my.ext']
 
     !!! note
         The preferred method is to pass in an instance of an extension. Strings
-		should only be used when it is impossible to import the Extension Class
-		directly (from the command line or in a template).
+        should only be used when it is impossible to import the Extension Class
+        directly (from the command line or in a template).
 
     When passing in extension instances, each class instance must be a subclass
     of `markdown.extensions.Extension` and any configuration options should be
     defined when initiating the class instance rather than using the
     [`extension_configs`](#extension_configs) keyword. For example:
 
+        :::python
         from markdown.extensions import Extension
         class MyExtension(Extension):
             # define your extension here...
@@ -91,24 +89,26 @@ __extensions__{: #extensions }
     If an extension name is provided as a string, the extension must be
     importable as a python module on your PYTHONPATH. Python's dot notation is
     supported. Therefore, to import the 'extra' extension, one could do
-    `extensions=['markdown.extensions.extra']`  
+    `extensions=['markdown.extensions.extra']`
 
-	Additionally, a Class may be specified in the name. The class must be at the end of
-	the name and be separated by a colon from the module.
+    Additionally, a Class may be specified in the name. The class must be at the
+    end of the name and be separated by a colon from the module.
 
-	Therefore, if you were to import the class like this:
+    Therefore, if you were to import the class like this:
 
-		from path.to.module import SomeExtensionClass
+        :::python
+        from path.to.module import SomeExtensionClass
 
-	Then the named extension would comprise this string:
+    Then the named extension would comprise this string:
 
-		"path.to.module:SomeExtensionClass"
+        :::python
+        "path.to.module:SomeExtensionClass"
 
-	!!! note
-		You should only need to specify the class name if more than one extension
-		is defined	within the same module. The extensions that come with
-		Python-Markdown do *not* need to have the class name specified. However,
-		doing so will not effect the behavior of the parser.
+    !!! note
+        You should only need to specify the class name if more than one extension
+        is defined  within the same module. The extensions that come with
+        Python-Markdown do *not* need to have the class name specified. However,
+        doing so will not effect the behavior of the parser.
 
     When loading an extension by name (as a string), you may pass in
     configuration settings to the extension using the
@@ -133,6 +133,7 @@ __extension_configs__{: #extension_configs }
 
     The dictionary of configuration settings must be in the following format:
 
+        :::python
         extension_configs = {
             'extension_name_1': {
                 'option_1': 'value_1',
@@ -152,8 +153,12 @@ __output_format__{: #output_format }:
 
     Supported formats are:
 
-    * `"xhtml"`: Outputs XHTML style tags. **Default**.
-    * `"html"`: Outputs HTML style tags.
+    * `"xhtml1"`: Outputs XHTML 1.x. **Default**.
+    * `"xhtml5"`: Outputs XHTML style tags of HTML 5
+    * `"xhtml"`: Outputs latest supported version of XHTML (currently XHTML 1.1).
+    * `"html4"`: Outputs HTML 4
+    * `"html5"`: Outputs HTML style tags of HTML 5
+    * `"html"`: Outputs latest supported version of HTML (currently HTML 4).
 
     The values can be in either lowercase or uppercase.
 
@@ -162,7 +167,9 @@ __output_format__{: #output_format }:
         `"html4"`) be used as the more general formats (`"xhtml"` or `"html"`) may
         change in the future if it makes sense at that time.
 
-* __`safe_mode`__{: #safe_mode }: Disallow raw HTML.
+__safe_mode__{: #safe_mode }:
+
+:    Disallow raw HTML.
 
     !!! warning
         "`safe_mode`" is deprecated and should not be used.
@@ -170,58 +177,75 @@ __output_format__{: #output_format }:
         HTML sanitizers (like [Bleach]) provide a better solution for
         dealing with markdown text submitted by untrusted users.
 
+            :::python
             import markdown
             import bleach
             html = bleach.clean(markdown.markdown(untrusted_text))
 
         See the [release notes] for more info.
 
-[Bleach]: https://github.com/jsocol/bleach
-[release notes]: release-2.6.html
-
     The following values are accepted:
 
-    * `False` (Default): Raw HTML is passed through unaltered.
+    `False` (Default):
 
-    * `replace`: Replace all HTML blocks with the text assigned to
-      `html_replacement_text` To maintain backward compatibility, setting
-      `safe_mode=True` will have the same effect as `safe_mode='replace'`.   
+    : Raw HTML is passed through unaltered.
+
+    `replace`:
+
+    : Replace all HTML blocks with the text assigned to
+      `html_replacement_text`. To maintain backward compatibility, setting
+      `safe_mode=True` will have the same effect as `safe_mode='replace'`.
 
         To replace raw HTML with something other than the default, do:
 
-            md = markdown.Markdown(safe_mode='replace',
-                               html_replacement_text='--RAW HTML NOT ALLOWED--')
+            :::python
+            md = markdown.Markdown(
+                safe_mode='replace',
+                html_replacement_text='--RAW HTML NOT ALLOWED--'
+            )
+
+    `remove`:
 
-    * `remove`: All raw HTML will be completely stripped from the text with
+    : All raw HTML will be completely stripped from the text with
       no warning to the author.
 
-    * `escape`: All raw HTML will be escaped and included in the document.
+    `escape`:
+
+    : All raw HTML will be escaped and included in the document.
 
         For example, the following source:
 
+            :::md
             Foo bar.
 
         Will result in the following HTML:
 
+            :::html
             
    Foo <b>bar</b>.
    
 
     !!! Note
         "safe_mode" also alters the default value for the
         [`enable_attributes`](#enable_attributes) option.
 
+[Bleach]: https://github.com/jsocol/bleach
+[release notes]: change_log/release-2.6.md
+
+__html_replacement_text__{: #html_replacement_text }:
 
-* __`html_replacement_text`__{: #html_replacement_text }: Text used when
-  safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`.
+: Text used when safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`.
 
     !!! warning
         "`html_replacement_text`" is deprecated and should not be used.
         See the [release notes] for more info.
 
-* __`tab_length`__{: #tab_length }: Length of tabs in the source. Default: 4
+__tab_length__{: #tab_length }:
+
+: Length of tabs in the source. Default: 4
+
+__enable_attributes__{: #enable_attributes}:
 
-* __`enable_attributes`__{: #enable_attributes}: Enable the conversion of
-  attributes. Defaults to `True`, unless [`safe_mode`](#safe_mode) is enabled,
-  in which case the default is `False`.
+: Enable the conversion of attributes. Defaults to `True`, unless
+  [`safe_mode`](#safe_mode) is enabled, in which case the default is `False`.
 
     !!! Note
         `safe_mode` only overrides the default. If `enable_attributes`
@@ -229,14 +253,17 @@ __output_format__{: #output_format }:
         However, this could potentially allow an untrusted user to inject
         JavaScript into your documents.
 
-* __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_`
-  intelligently Default: True
+__smart_emphasis__{: #smart_emphasis }:
 
-* __`lazy_ol`__{: #lazy_ol }: Ignore number of first item of ordered lists.
-  Default: True
+: Treat `_connected_words_` intelligently Default: True
+
+__lazy_ol__{: #lazy_ol }:
+
+: Ignore number of first item of ordered lists. Default: True
 
     Given the following list:
 
+        :::md
         4. Apples
         5. Oranges
         6. Pears
@@ -246,14 +273,13 @@ __output_format__{: #output_format }:
     If `lazy_ol` is set to `False`, then markdown will output the following
     HTML:
 
+        :::html
         
      
           
    1. Apples
      2. 
           
    2. Oranges
      3. 
           
    3. Pears
      4. 
         
    
 
-:   Length of tabs in the source. Default: 4
-
 ### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile }
 
 With a few exceptions, `markdown.markdownFromFile` accepts the same options as
@@ -308,22 +334,27 @@ argument of the [`markdown.markdown`](#markdown) function.
 You should also use this method if you want to process multiple strings
 without creating a new instance of the class for each string.
 
-    md = markdown.Markdown()
-    html1 = md.convert(text1)
-    html2 = md.convert(text2)
+```python
+md = markdown.Markdown()
+html1 = md.convert(text1)
+html2 = md.convert(text2)
+```
 
 Depending on which options and/or extensions are being used, the parser may
 need its state reset between each call to `convert`, otherwise performance
 can degrade drastically:
 
-    html1 = md.convert(text1)
-    md.reset()
-    html2 = md.convert(text2)
+```python
+html1 = md.convert(text1)
+md.reset()
+html2 = md.convert(text2)
+```
 
 To make this easier, you can also chain calls to `reset` together:
 
-    html3 = md.reset().convert(text3)
-
+```python
+html3 = md.reset().convert(text3)
+```
 
 #### Markdown.convertFile(**kwargs) {: #convertFile }
 
diff --git a/docs/test_suite.md b/docs/test_suite.md
index ee761f2d4..9ead4c605 100644
--- a/docs/test_suite.md
+++ b/docs/test_suite.md
@@ -7,10 +7,10 @@ next_url:   change_log.html
 # Test Suite
 
 Python-Markdown comes with a test suite which uses the [Nose] testing
-framework and [YAML]. The test suite primarily serves to ensure that new bugs 
-are not introduced as existing bugs are patched or new features are added. It 
-also allows Python-Markdown to be tested with the tests from other 
-implementations such as John Gruber's [Perl] implementation or Michel 
+framework and [YAML]. The test suite primarily serves to ensure that new bugs
+are not introduced as existing bugs are patched or new features are added. It
+also allows Python-Markdown to be tested with the tests from other
+implementations such as John Gruber's [Perl] implementation or Michel
 Fortin's [PHP] implementation.
 
 The test suite can be run by calling the `run_tests.py` command at the root of
@@ -24,8 +24,8 @@ temporary file in `test-output.html`. Open the file in a browser to view
 the report.
 
 A `tox.ini` file is also provided, so [tox] can be used to automatically create
-virtual environments, install all testing dependencies and run the tests on 
-each supported Python version. See the wiki for instructions on 
+virtual environments, install all testing dependencies and run the tests on
+each supported Python version. See the wiki for instructions on
 [setting up a testing environment] to use tox.
 
 The test suite contains two kinds of tests: Markdown Syntax Tests and Unit
@@ -61,18 +61,18 @@ insignificant white space differences:
     MarkdownSyntaxError: Output from "/home/waylan/code/python-markdown/te
     sts/misc/lists3.txt" failed to match expected output.
 
-    --- /home/waylan/code/python-markdown/tests/misc/lists3.html 
-    +++ actual_output.html 
-    @@ -1,5 +1,5 @@ 
-     
       
-     
    • blah blah blah 
-    -sdf asdf asdf asdf asdf 
-    -asda asdf asdfasd
      •  
-    +    sdf asdf asdf asdf asdf 
-    +    asda asdf asdfasd 
+    --- /home/waylan/code/python-markdown/tests/misc/lists3.html
+    +++ actual_output.html
+    @@ -1,5 +1,5 @@
+     
        
+     
      • blah blah blah
+    -sdf asdf asdf asdf asdf
+    -asda asdf asdfasd
        • 
+    +    sdf asdf asdf asdf asdf
+    +    asda asdf asdfasd
      
      
 
-    ---------------------------------------------------------------------- 
+    ----------------------------------------------------------------------
     Ran 219 tests in 7.698s
 
     FAILED (MarkdownSyntaxError=1, SKIP=53)
@@ -109,29 +109,29 @@ settings under a specific file section will override anything in the
 Below are the configuration options available and the defaults used when they
 are not explicitly set.
 
-* `normalize`: Switches white space normalization of the test output on or off. 
-  Defaults to `False` (off). Note: This requires that [PyTidyLib] be installed on 
-  the system. Otherwise the test will be skipped, regardless of any other 
-  settings.  
-* `skip`: Switches skipping of the test on and off. Defaults to `False` (off).  
-* `input_ext`: Extension of input file. Defaults to `.txt`. Useful for tests 
+* `normalize`: Switches white space normalization of the test output on or off.
+  Defaults to `False` (off). Note: This requires that [PyTidyLib] be installed
+  on the system. Otherwise the test will be skipped, regardless of any other
+  settings.
+* `skip`: Switches skipping of the test on and off. Defaults to `False` (off).
+* `input_ext`: Extension of input file. Defaults to `.txt`. Useful for tests
   from other implementations.
 * `output_ext`: Extension of output file. Defaults to `.html`. Useful for tests
   from other implementations.
-* Any keyword argument accepted by the Markdown class. If not set, Markdown's 
-  defaults are used. 
+* Any keyword argument accepted by the Markdown class. If not set, Markdown's
+  defaults are used.
 
 ## Unit Tests
 
 Unit Tests are used as regression tests for Python-Markdown's API.
 All Unit Tests shipped with Python-Markdown are standard Python Unit Tests and
-are all contained in `tests/test_apis.py` and `tests/test_extensions.py`. 
-Standard discovery methods are used to find and run the tests. Therefore, when 
+are all contained in `tests/test_apis.py` and `tests/test_extensions.py`.
+Standard discovery methods are used to find and run the tests. Therefore, when
 writing new tests, those standards and naming conventions should be followed.
 
-[Nose]: http://somethingaboutorange.com/mrl/projects/nose/ 
-[Perl]: http://daringfireball.net/projects/markdown/ 
-[PHP]: http://michelf.com/projects/php-markdown/ 
+[Nose]: http://somethingaboutorange.com/mrl/projects/nose/
+[Perl]: http://daringfireball.net/projects/markdown/
+[PHP]: http://michelf.com/projects/php-markdown/
 [PyTidyLib]: http://countergram.com/open-source/pytidylib/
 [tox]: http://testrun.org/tox/latest/
 [setting up a testing environment]: https://github.com/Python-Markdown/markdown/wiki/Test-Environment-Setup