diff options
Diffstat (limited to 'docs/change_log')
| -rw-r--r-- | docs/change_log/index.md | 226 | ||||
| -rw-r--r-- | docs/change_log/release-2.0.md | 69 | ||||
| -rw-r--r-- | docs/change_log/release-2.1.md | 119 | ||||
| -rw-r--r-- | docs/change_log/release-2.2.md | 64 | ||||
| -rw-r--r-- | docs/change_log/release-2.3.md | 85 | ||||
| -rw-r--r-- | docs/change_log/release-2.4.md | 73 | ||||
| -rw-r--r-- | docs/change_log/release-2.5.md | 189 | ||||
| -rw-r--r-- | docs/change_log/release-2.6.md | 306 |
8 files changed, 1131 insertions, 0 deletions
diff --git a/docs/change_log/index.md b/docs/change_log/index.md new file mode 100644 index 0000000..8f921e1 --- /dev/null +++ b/docs/change_log/index.md @@ -0,0 +1,226 @@ +title: Change Log + +Python-Markdown Change Log +========================= + +Aug 17, 2017: Released version 2.6.9 (a bug-fix release). + +Jan 25, 2017: Released version 2.6.8 (a bug-fix release). + +Sept 23, 2016: Released version 2.6.7 (a bug-fix release). + +Mar 20, 2016: Released version 2.6.6 (a bug-fix release). + +Nov 24, 2015: Released version 2.6.5 (a bug-fix release). + +Nov 6, 2015: Released version 2.6.4 (a bug-fix release). + +Oct 26, 2015: Released version 2.6.3 (a bug-fix release). + +Apr 20, 2015: Released version 2.6.2 (a bug-fix release). + +Mar 8, 2015: Released version 2.6.1 (a bug-fix release). The (new) +`yaml` option has been removed from the Meta-Data Extension as it was buggy +(see [#390](https://github.com/Python-Markdown/markdown/issues/390)). + +Feb 19, 2015: Released version 2.6 ([Notes](release-2.6.md)). + +Nov 19, 2014: Released version 2.5.2 (a bug-fix release). + +Sept 26, 2014: Released version 2.5.1 (a bug-fix release). + +Sept 12, 2014: Released version 2.5.0 ([Notes](release-2.5.md)). + +Feb 16, 2014: Released version 2.4.0 ([Notes](release-2.4.md)). + +Mar 22, 2013: Released version 2.3.1 (a bug-fix release). + +Mar 14, 2013: Released version 2.3.0 ([Notes](release-2.3.md)) + +Nov 4, 2012: Released version 2.2.1 (a bug-fix release). + +Jul 5, 2012: Released version 2.2.0 ([Notes](release-2.2.md)). + +Jan 22, 2012: Released version 2.1.1 (a bug-fix release). + +Nov 24, 2011: Released version 2.1.0 ([Notes](release-2.1.md)). + +Oct 7, 2009: Released version 2.0.3. (a bug-fix release). + +Sept 28, 2009: Released version 2.0.2 (a bug-fix release). + +May 20, 2009: Released version 2.0.1 (a bug-fix release). + +Mar 30, 2009: Released version 2.0 ([Notes](release-2.0.md)). + +Mar 8, 2009: Release Candidate 2.0-rc-1. + +Feb 2009: Added support for multi-level lists to new Blockprocessors. + +Jan 2009: Added HTML 4 output as an option (thanks Eric Abrahamsen) + +Nov 2008: Added Definition List ext. Replaced old core with Blockprocessors. +Broken up into multiple files. + +Oct 2008: Changed logging behavior to work better with other systems. +Refactored tree traversing. Added `treap` implementation, then replaced with +OrderedDict. Renamed various processors to better reflect what they actually +do. Refactored footnote ext to match PHP Extra's output. + +Sept 2008: Moved `prettifyTree` to a Postprocessor, replaced WikiLink ext +with WikiLinks (note the s) ext (uses bracketed links instead of CamelCase) +and various bug fixes. + +August 18 2008: Reorganized directory structure. Added a 'docs' directory +and moved all extensions into a 'markdown-extensions' package. +Added additional documentation and a few bug fixes. (v2.0-beta) + +August 4 2008: Updated included extensions to ElementTree. Added a +separate command line script. (v2.0-alpha) + +July 2008: Switched from home-grown NanoDOM to ElementTree and +various related bugs (thanks Artem Yunusov). + +June 2008: Fixed issues with nested inline patterns and cleaned +up testing framework (thanks Artem Yunusov). + +May 2008: Added a number of additional extensions to the +distribution and other minor changes. Moved repository to git from svn. + +Mar 2008: Refactored extension API to accept either an +extension name (as a string) or an instance of an extension +(Thanks David Wolever). Fixed various bugs and added doc strings. + +Feb 2008: Various bug-fixes mostly regarding extensions. + +Feb 18, 2008: Version 1.7. + +Feb 13, 2008: A little code cleanup and better documentation +and inheritance for Preprocessors/Postprocessors. + +Feb 9, 2008: Double-quotes no longer HTML escaped and raw HTML +honors `<?foo>`, `<@foo>`, and `<%foo>` for those who run markdown on +template syntax. + +Dec 12, 2007: Updated docs. Removed encoding argument from Markdown +and markdown as per list discussion. Clean up in prep for 1.7. + +Nov 29, 2007: Added support for images inside links. Also fixed +a few bugs in the footnote extension. + +Nov 19, 2007: `message` now uses python's logging module. Also removed +limit imposed by recursion in `_process_section()`. You can now parse as +long of a document as your memory can handle. + +Nov 5, 2007: Moved `safe_mode` code to a `textPostprocessor` and added +escaping option. + +Nov 3, 2007: Fixed convert method to accept empty strings. + +Oct 30, 2007: Fixed `BOM` removal (thanks Malcolm Tredinnick). Fixed +infinite loop in bracket regular expression for inline links. + +Oct 11, 2007: `LineBreaks` is now an `inlinePattern`. Fixed `HR` in +blockquotes. Refactored `_processSection` method (see tracker #1793419). + +Oct 9, 2007: Added `textPreprocessor` (from 1.6b). + +Oct 8, 2008: Fixed Lazy Blockquote. Fixed code block on first line. +Fixed empty inline image link. + +Oct 7, 2007: Limit recursion on inline patterns. Added a 'safe' tag +to `htmlStash`. + +March 18, 2007: Fixed or merged a bunch of minor bugs, including +multi-line comments and markup inside links. (Tracker #s: 1683066, +1671153, 1661751, 1627935, 1544371, 1458139.) -> v. 1.6b + +Oct 10, 2006: Fixed a bug that caused some text to be lost after +comments. Added "safe mode" (user's HTML tags are removed). + +Sept 6, 2006: Added exception for PHP tags when handling HTML blocks. + +August 7, 2006: Incorporated Sergej Chodarev's patch to fix a problem +with ampersand normalization and HTML blocks. + +July 10, 2006: Switched to using `optparse`. Added proper support for +Unicode. + +July 9, 2006: Fixed the `<!--@address.com>` problem (Tracker #1501354). + +May 18, 2006: Stopped catching unquoted titles in reference links. +Stopped creating blank headers. + +May 15, 2006: A bug with lists, recursion on block-level elements, +run-in headers, spaces before headers, Unicode input (thanks to Aaron +Swartz). Sourceforge tracker #s: 1489313, 1489312, 1489311, 1488370, +1485178, 1485176. (v. 1.5) + +Mar. 24, 2006: Switched to a not-so-recursive algorithm with +`_handleInline`. (Version 1.4) + +Mar. 15, 2006: Replaced some instance variables with class variables +(a patch from Stelios Xanthakis). Chris Clark's new regexps that do +not trigger mid-word underlining. + +Feb. 28, 2006: Clean-up and command-line handling by Stewart +Midwinter. (Version 1.3) + +Feb. 24, 2006: Fixed a bug with the last line of the list appearing +again as a separate paragraph. Incorporated Chris Clark's "mail-to" +patch. Added support for `<br />` at the end of lines ending in two or +more spaces. Fixed a crashing bug when using `ImageReferencePattern`. +Added several utility methods to `Nanodom`. (Version 1.2) + +Jan. 31, 2006: Added `hr` and `hr/` to BLOCK_LEVEL_ELEMENTS and +changed `<hr/>` to `<hr />`. (Thanks to Sergej Chodarev.) + +Nov. 26, 2005: Fixed a bug with certain tabbed lines inside lists +getting wrapped in `<pre><code>`. (v. 1.1) + +Nov. 19, 2005: Made `<!...`, `<?...`, etc. behave like block-level +HTML tags. + +Nov. 14, 2005: Added entity code and email auto-link fix by Tiago +Cogumbreiro. Fixed some small issues with backticks to get 100% +compliance with John's test suite. (v. 1.0) + +Nov. 7, 2005: Added an `unlink` method for documents to aid with memory +collection (per Doug Sauder's suggestion). + +Oct. 29, 2005: Restricted a set of HTML tags that get treated as +block-level elements. + +Sept. 18, 2005: Refactored the whole script to make it easier to +customize it and made footnote functionality into an extension. +(v. 0.9) + +Sept. 5, 2005: Fixed a bug with multi-paragraph footnotes. Added +attribute support. + +Sept. 1, 2005: Changed the way headers are handled to allow inline +syntax in headers (e.g. links) and got the lists to use p-tags +correctly (v. 0.8) + +Aug. 29, 2005: Added flexible tabs, fixed a few small issues, added +basic support for footnotes. Got rid of xml.dom.minidom and added +pretty-printing. (v. 0.7) + +Aug. 13, 2005: Fixed a number of small bugs in order to conform to the +test suite. (v. 0.6) + +Aug. 11, 2005: Added support for inline HTML and entities, inline +images, auto-links, underscore emphasis. Cleaned up and refactored the +code, added some more comments. + +Feb. 19, 2005: Rewrote the handling of high-level elements to allow +multi-line list items and all sorts of nesting. + +Feb. 3, 2005: Reference-style links, single-line lists, backticks, +escape, emphasis in the beginning of the paragraph. + +Nov. 2004: Added links, blockquotes, HTML blocks to Manfred +Stienstra's code + +Apr. 2004: Manfred's version at <http://www.dwerg.net/projects/markdown/> + diff --git a/docs/change_log/release-2.0.md b/docs/change_log/release-2.0.md new file mode 100644 index 0000000..abd8d29 --- /dev/null +++ b/docs/change_log/release-2.0.md @@ -0,0 +1,69 @@ +title: Release Notes for v2.0 + +Python-Markdown 2.0 Release Notes +================================= + +We are happy to release Python-Markdown 2.0, which has been over a year in the +making. We have rewritten significant portions of the code, dramatically +extending the extension API, increased performance, and added numerous +extensions to the distribution (including an extension that mimics PHP Markdown +Extra), all while maintaining backward compatibility with the end user API in +version 1.7. + +Python-Markdown supports Python versions 2.3, 2.4, 2.5, and 2.6. We have even +released a version converted to Python 3.0! + +Backwards-incompatible Changes +------------------------------ + +While Python-Markdown has experienced numerous internal changes, those changes +should only affect extension authors. If you have not written your own +extensions, then you should not need to make any changes to your code. +However, you may want to ensure that any third party extensions you are using +are compatible with the new API. + +The new extension API is fully [documented](../extensions/api.md) in the docs. +Below is a summary of the significant changes: + +* The old home-grown NanoDOM has been replaced with ElementTree. Therefore all + extensions must use ElementTree rather than the old NanoDOM. +* The various processors and patterns are now stored with OrderedDicts rather + than lists. Any code adding processors and/or patterns into Python-Markdown + will need to be adjusted to use the new API using OrderedDicts. +* The various types of processors available have been either combined, added, + or removed. Ensure that your processors match the currently supported types. + +What's New in Python-Markdown 2.0 +--------------------------------- + +Thanks to the work of Artem Yunusov as part of GSoC 2008, Python-Markdown uses +ElementTree internally to build the (X)HTML document from markdown source text. +This has resolved various issues with the older home-grown NanoDOM and made +notable increases in performance. + +Artem also refactored the Inline Patterns to better support nested patterns +which has resolved many inconsistencies in Python-Markdown's parsing of the +markdown syntax. + +The core parser had been completely rewritten, increasing performance and, for +the first time, making it possible to override/add/change the way block level +content is parsed. + +Python-Markdown now parses markdown source text more closely to the other +popular implementations (Perl, PHP, etc.) than it ever has before. With the +exception of a few minor insignificant differences, any difference should be +considered a bug, rather than a limitation of the parser. + +The option to return HTML4 output as apposed to XHTML has been added. In +addition, extensions should be able to easily add additional output formats. + +As part of implementing markdown in the Dr. Project project (a Trac fork), among +other things, David Wolever refactored the "extension" keyword so that it +accepts either the extension names as strings or instances of extensions. This +makes it possible to include multiple extensions in a single module. + +Numerous extensions are included in the distribution by default. See +[available_extensions](../extensions/index.md) for a complete list. + +See the [Change Log](index.md) for a full list of changes. + diff --git a/docs/change_log/release-2.1.md b/docs/change_log/release-2.1.md new file mode 100644 index 0000000..30cf0b2 --- /dev/null +++ b/docs/change_log/release-2.1.md @@ -0,0 +1,119 @@ +title: Release Notes for v2.1 + +Python-Markdown 2.1 Release Notes +================================= + +We are pleased to release Python-Markdown 2.1 which makes many +improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. +While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline +with other implementations, some internal improvements were made to the parser, +a few new built-in extensions were added, and HTML5 support was added. + +Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out +of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no +extra work by the end user. + +Backwards-incompatible Changes +------------------------------ + +While Python-Markdown has received only minor internal changes since the last +release, there are a few backward-incompatible changes to note: + +* Support had been dropped for Python 2.3. No guarantees are made that the + library will work in any version of Python lower than 2.4. Additionally, while + the library had been tested with Python 2.4, consider Python 2.4 support to be + depreciated. It is not likely that any future versions will continue to + support any version of Python less than 2.5. Note that Python 3.0 is not + supported due to a bug in its 2to3 tool. If you must use Python-Markdown with + Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to do a + conversion. + +* Python-Markdown previously accepted positional arguments on its class and + wrapper methods. It now expects keyword arguments. Currently, the positional + arguments should continue to work, but the solution feels hacky and may be + removed in a future version. All users are encouraged to use keyword arguments + as documented in the [Library Reference](../reference.md). + +* Past versions of Python-Markdown provided module level Global variables which + controlled the behavior of a few different aspects of the parser. Those global + variables have been replaced with attributes on the Markdown class. + Additionally, those attributes are settable as keyword arguments when + initializing a class instance. Therefore, if you were editing the global + variables (either by editing the source or by overriding them in your code), + you should now set them on the class. See the [Library + Reference](../reference.md) for the options available. + +* If you have been using the [HeaderId](../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. + +What's New in Python-Markdown 2.1 +--------------------------------- + +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 +introduced in the HTML5 spec are now properly recognized as raw HTML. As +valid HTML5 can consist of either HTML4 or XHTML1, there is no need to add a +new HTML5 serializers. That said, `html5` and `xhtml5` have been added as +aliases of the `html4` and `xhtml1` serializers respectively. + +An XHTML serializer has been added. Previously, ElementTree's XML serializer +was being used for XHTML output. With the new serializer we are able to avoid +more invalid output like empty elements (i.e., `<p />`) which can choke +browsers. + +Improved support for Python 3.x. Now when running `setupy.py install` in +Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 +is not supported due to a bug in its 2to3 tool. If you must use Python-Markdown +with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to +do a conversion. + +Methods on instances of the Markdown class that do not return results can now +be changed allowing one to do `md.reset().convert(moretext)`. + +The Markdown class was refactored so that a subclass could define it's own +`build_parser` method which would build a completely different parser. In +other words, one could use the basic machinery in the markdown library to +build a parser of a different markup language without the overhead of building +the markdown parser and throwing it away. + +Import statements within markdown have been improved so that third party +libraries can embed the markdown library if they desire (licensing permitting). + +Added support for Python's `-m` command line option. You can run the markdown +package as a command line script. Do `python -m markdown [options] [args]`. +Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 +require you to call the module directly (`markdown.__main__`) rather than +the package (`markdown`). This does not work in Python 2.4. + +The command line script has been renamed to `markdown_py` which avoids all the +various problems we had with previous names. Also improved the command line +script to accept input on `stdin`. + +The testing framework has been completely rebuilt using the Nose testing +framework. This provides a number of benefits including the ability to better +test the built-in extensions and other options available to change the parsing +behavior. See the [Test Suite](../test_suite.md) documentation for details. + +Various bug fixes have been made, which are too numerous to list here. See the +[commit log](https://github.com/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 new file mode 100644 index 0000000..379a43e --- /dev/null +++ b/docs/change_log/release-2.2.md @@ -0,0 +1,64 @@ +title: Release Notes for v2.2 + +Python-Markdown 2.2 Release Notes +================================= + +We are pleased to release Python-Markdown 2.2 which makes improvements on 2.1. +While 2.2 is primarily a bug fix release, some internal improvements were made +to the parser, and a few security issues were resolved. + +Python-Markdown supports Python versions 2.5, 2.6, 2.7, 3.1, and 3.2 out +of the box. + +Backwards-incompatible Changes +------------------------------ + +While Python-Markdown has received only minor internal changes since the last +release, there are a few backward-incompatible changes to note: + +* Support had been dropped for Python 2.4. No guarantees are made that the + library will work in any version of Python lower than 2.5. Additionally, while + the library had been tested with Python 2.5, consider Python 2.5 support to be + depreciated. It is not likely that any future versions will continue to + support any version of Python less than 2.6. + +* For many years Python-Markdown has identified `<ins>` and `<del>` tags in raw + HTML input as block level tags. As they are actually inline level tags, this + behavior has been changed. This may result in slightly different output. While + in most cases, the new output is more correct, there may be a few edge cases + where a document author has relied on the previous incorrect behavior. It is + likely that a few adjustments may need to be made to those documents. + +* The behavior of the `enable_attributes` keyword has been slightly altered. If + authors have been using attributes in documents with `safe_mode` on, those + attributes will no longer be parsed unless `enable_attributes` is explicitly + set to `True`. This change was made to prevent untrusted authors from + injecting potentially harmful JavaScript in documents. This change had no + effect when not in `safe_mode`. + +What's New in Python-Markdown 2.2 +--------------------------------- + +The docs were refactored and can now be found at +<http://packages.python.org/Markdown/>. The docs are now maintained in the +Repository and are generated by the `setup.py build_docs` command. + +The [Sane_Lists](../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 new file mode 100644 index 0000000..fc1809e --- /dev/null +++ b/docs/change_log/release-2.3.md @@ -0,0 +1,85 @@ +title: Release Notes for v2.3 + +Python-Markdown 2.3 Release Notes +================================= + +We are pleased to release Python-Markdown 2.3 which adds one new extension, +removes a few old (obsolete) extensions, and now runs on both Python 2 and +Python 3 without running the 2to3 conversion tool. See the list of changes +below for details. + +Python-Markdown supports Python versions 2.6, 2.7, 3.1, 3.2, and 3.3. + +Backwards-incompatible Changes +------------------------------ + +* Support has been dropped for Python 2.5. No guarantees are made that the + library will work in any version of Python lower than 2.6. As all supported + Python versions include the ElementTree library, Python-Markdown will no + longer try to import a third-party installation of ElementTree. + +* All classes are now "new-style" classes. In other words, all classes subclass + from 'object'. While this is not likely to affect most users, extension + authors may need to make a few minor adjustments to their code. + +* "safe_mode" has been further restricted. Markdown formatted links must be of a + known white-listed scheme when in "safe_mode" or the URL is discarded. The + white-listed schemes are: 'HTTP', 'HTTPS', 'FTP', 'FTPS', 'MAILTO', and + 'news'. Schemeless URLs are also permitted, but are checked in other ways - as + they have been for some time. + +* The ids assigned to footnotes now contain a dash (`-`) rather than a colon + (`:`) when `output_format` it set to `"html5"` or `"xhtml5"`. If you are + making reference to those ids in your JavaScript or CSS and using the HTML5 + output, you will need to update your code accordingly. No changes are + necessary if you are outputting XHTML (the default) or HTML4. + +* The `force_linenos` configuration setting of the CodeHilite extension has been + marked as **Pending Deprecation** and a new setting `linenums` has been added + to replace it. See documentation for the [CodeHilite Extension] for an + explanation of the new `linenums` setting. The new setting will honor the old + `force_linenos` if it is set, but it will raise a `PendingDeprecationWarning` + and will likely be removed in a future version of Python-Markdown. + +[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={...})`). + +[PyTidyLib]: http://countergram.com/open-source/pytidylib + +What's New in Python-Markdown 2.3 +--------------------------------- + +* The entire code base now universally runs in Python 2 and Python 3 without any + need for running the 2to3 conversion tool. This not only simplifies testing, + but by using Unicode_literals, results in more consistent behavior across + Python versions. Additionally, the relative imports (made possible in Python 2 + via absolute_import) allows the entire library to more easily be embedded in a + sub-directory of another project. The various files within the library will + still import each other properly even though 'markdown' may not be in Python's + root namespace. + +* The [Admonition Extension] has been added, which implements [rST-style][rST] + admonitions in the Markdown syntax. However, be warned that this extension is + experimental and the syntax and behavior is still subject to change. Please + try it out and report bugs and/or improvements. + +[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. diff --git a/docs/change_log/release-2.4.md b/docs/change_log/release-2.4.md new file mode 100644 index 0000000..19130f1 --- /dev/null +++ b/docs/change_log/release-2.4.md @@ -0,0 +1,73 @@ +title: Release Notes for v2.4 + +Python-Markdown 2.4 Release Notes +================================= + +We are pleased to release Python-Markdown 2.4 which adds one new extension +and fixes various bugs. See the list of changes below for details. + +Python-Markdown supports Python versions 2.6, 2.7, 3.1, 3.2, and 3.3. + +Backwards-incompatible Changes +------------------------------ + +* The `force_linenos` configuration setting of the CodeHilite extension has been + marked as **Deprecated**. It had previously been marked as "Pending + Deprecation" in version 2.3 when a new setting `linenums` was added to replace + it. See documentation for the [CodeHilite Extension] for an explanation of the + new `linenums` setting. The new setting will honor the old `force_linenos` if + it is set, but `force_linenos` will raise a `DeprecationWarning` and will + likely be removed in a future version of Python-Markdown. + +[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. + +What's New in Python-Markdown 2.4 +--------------------------------- + +* Thanks to the hard work of [Dmitry Shachnev] the [Smarty Extension] has been + added, which implements [SmartyPants] using Python-Markdown's Extension API. + This offers a few benefits over a third party script. The HTML does not need + to be "tokenized" twice, no hacks are required to combine SmartyPants and code + highlighting, and we get markdown's escaping feature for free. Please try it + out and report bugs and/or improvements. + +[Dmitry Shachnev]: https://github.com/mitya57 +[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. + +[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. + +[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]): + + ```.python hl_lines="1 3" + # This line will be emphasized. + # This one won't. + # This one will be also emphasized. + ``` + + Thanks to [A. Jesse Jiryu Davis] for implementing this feature. + +[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. diff --git a/docs/change_log/release-2.5.md b/docs/change_log/release-2.5.md new file mode 100644 index 0000000..f6a4e36 --- /dev/null +++ b/docs/change_log/release-2.5.md @@ -0,0 +1,189 @@ +title: Release Notes for v2.5 + +Python-Markdown 2.5 Release Notes +================================= + +We are pleased to release Python-Markdown 2.5 which adds a few new features +and fixes various bugs. See the list of changes below for details. + +Python-Markdown version 2.5 supports Python versions 2.7, 3.2, 3.3, and 3.4. + +Backwards-incompatible Changes +------------------------------ + +* Python-Markdown no longer supports Python version 2.6. You must be using Python + versions 2.7, 3.2, 3.3, or 3.4. + +[importlib]: https://pypi.python.org/pypi/importlib + +* The `force_linenos` configuration key on the [CodeHilite Extension] has been **deprecated** + and will raise a `KeyError` if provided. In the previous release (2.4), it was + issuing a `DeprecationWarning`. The [`linenums`][linenums] keyword should be used + instead, which provides more control of the output. + +[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. + + If your code previously looked like this: + + html = markdown.markdown(text, same_mode=True) + + Then it is recommended that you change your code to read something like this: + + import bleach + html = bleach.clean(markdown.markdown(text)) + + If you are not interested in sanitizing untrusted text, but simply desire to + escape raw HTML, then that can be accomplished through an extension which + removes HTML parsing: + + from markdown.extensions import Extension + + class EscapeHtml(Extension): + def extendMarkdown(self, md, md_globals): + del md.preprocessors['html_block'] + del md.inlinePatterns['html'] + + html = markdown.markdown(text, extensions=[EscapeHtml()]) + + As the HTML would not be parsed with the above Extension, then the + serializer will escape the raw HTML, which is exactly what happens now when + `safe_mode="escape"`. + +[Bleach]: https://bleach.readthedocs.io/ + +* Positional arguments on the `markdown.Markdown()` are pending deprecation as are + all except the `text` argument on the `markdown.markdown()` wrapper function. + Only keyword arguments should be used. For example, if your code previously + looked like this: + + html = markdown.markdown(text, ['extra']) + + Then it is recommended that you change it to read something like this: + + html = markdown.markdown(text, extensions=['extra']) + + !!! Note + This change is being made as a result of deprecating `"safe_mode"` as the + `safe_mode` argument was one of the positional arguments. When that argument + is removed, the two arguments following it will no longer be at the correct + position. It is recommended that you always use keywords when they are supported + for this reason. + +* In previous versions of Python-Markdown, the built-in extensions received + special status and did not require the full path to be provided. Additionally, + third party extensions whose name started with `"mdx_"` received the same + special treatment. This behavior will be deprecated in version 2.6 and will + raise a **`PendingDeprecationWarning`** in 2.5. Ensure that you always use the + full path to your extensions. For example, if you previously did the + following: + + markdown.markdown(text, extensions=['extra']) + + You should change your code to the following: + + markdown.markdown(text, extensions=['markdown.extensions.extra']) + + The same applies to the command line: + + $ python -m markdown -x markdown.extensions.extra input.txt + + See the [documentation](../reference.md#extensions) for a full explanation + of the current behavior. + +* The previously documented method of appending the extension configuration as + a string to the extension name will be deprecated in Python-Markdown + version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. The + [`extension_configs`](../reference.md#extension_configs) keyword should + be used instead. See the [documentation](../reference.md#extension-configs) + for a full explanation of the current behavior. + +What's New in Python-Markdown 2.5 +--------------------------------- + +* The [Smarty Extension] has had a number of additional configuration settings + added, which allows one to define their own substitutions to better support + languages other than English. Thanks to [Martin Altmayer] for implementing this + feature. + +[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. + + Additionally, a Class may be specified in the name. The class must be at the + end of the name (which uses dot notation from PYTHONPATH) and be separated + by a colon from the module. + + Therefore, if you were to import the class like this: + + from path.to.module import SomeExtensionClass + + Then the named extension would comprise this string: + + "path.to.module:SomeExtensionClass" + + This allows multiple extensions to be implemented within the same module and + still accessible when the user is not able to import the extension directly + (perhaps from a template filter or the command line). + + This also means that extension modules are no longer required to include the + `makeExtension` function which returns an instance of the extension class. + However, if the user does not specify the class name (she only provides + `"path.to.module"`) the extension will fail to load without the + `makeExtension` function included in the module. Extension authors will want + to document carefully what is required to load their extensions. + +[ex]: ../reference.md#extensions + +* The Extension Configuration code has been refactored to make it a little + easier for extension authors to work with configuration settings. As a + result, the [`extension_configs`][ec] keyword now accepts a dictionary + rather than requiring a list of tuples. A list of tuples is still supported + so no one needs to change their existing code. This should also simplify the + learning curve for new users. + + Extension authors are encouraged to review the new methods available on the + `markdown.extnesions.Extension` class for handling configuration and adjust + their code going forward. The included extensions provide a model for best + practices. See the [API] documentation for a full explanation. + +[ec]: ../reference.md#extension_configs +[API]: ../extensions/api.md#configsettings + +* The [Command Line Interface][cli] now accepts a `--extensions_config` (or + `-c`) option which accepts a file name and passes the parsed content of a + [YAML] or [JSON] file to the [`extension_configs`][ec] keyword of the + `markdown.Markdown` class. The contents of the YAML or JSON must map to a + Python Dictionary which matches the format required by the + `extension_configs` keyword. Note that [PyYAML] is required to parse YAML + files. + +[cli]: ../cli.md#using-extensions +[YAML]: http://yaml.org/ +[JSON]: http://json.org/ +[PyYAML]: http://pyyaml.org/ + +* The [Admonition Extension][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. + +* 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 new file mode 100644 index 0000000..1495072 --- /dev/null +++ b/docs/change_log/release-2.6.md @@ -0,0 +1,306 @@ +title: Release Notes for v2.6 + +# Python-Markdown 2.6 Release Notes + +We are pleased to release Python-Markdown 2.6 which adds a few new features +and fixes various bugs. See the list of changes below for details. + +Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as +well as PyPy. + +## Backwards-incompatible Changes + +### `safe_mode` Deprecated + +Both `safe_mode` and the associated `html_replacement_text` keywords are +deprecated in version 2.6 and will raise a **`DeprecationWarning`**. The +`safe_mode` and `html_replacement_text` keywords will be ignored in 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: + +```python +html = markdown.markdown(text, safe_mode=True) +``` + +Then it is recommended that you change your code to read something like this: + +```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: + +```python +from markdown.extensions import Extension + +class EscapeHtml(Extension): + def extendMarkdown(self, md, md_globals): + del md.preprocessors['html_block'] + del md.inlinePatterns['html'] + +html = markdown.markdown(text, extensions=[EscapeHtml()]) +``` + +As the HTML would not be parsed with the above Extension, then the serializer +will escape the raw HTML, which is exactly what happens now when +`safe_mode="escape"`. + +[Bleach]: 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 the next release. Only keyword arguments should be used. For example, +if your code previously looked like this: + +```python +html = markdown.markdown(text, [SomeExtension()]) +``` + +Then it is recommended that you change it to read something like this: + +```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. + +### "Shortened" Extension Names Deprecated + +In previous versions of Python-Markdown, the built-in extensions received +special status and did not require the full path to be provided. Additionally, +third party extensions whose name started with `"mdx_"` received the same +special treatment. This behavior is deprecated and will raise a +**`DeprecationWarning`** in version 2.6 and an error in the next release. Ensure +that you always use the full path to your extensions. For example, if you +previously did the following: + +```python +markdown.markdown(text, extensions=['extra']) +``` + +You should change your code to the following: + +```python +markdown.markdown(text, extensions=['markdown.extensions.extra']) +``` + +The same applies to the command line: + +```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: + +```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): + +```python +markdown.markdown(text, extensions=['mdx_math']) +``` + +Extension authors will want to update their documentation to reflect the new +behavior. + +See the [documentation](../reference.md#extensions) for a full explanation +of the current behavior. + +### Extension Configuration as Part of Extension Name Deprecated + +The previously documented method of appending the extension configuration +options as a string to the extension name is deprecated and will raise a +**`DeprecationWarning`** in version 2.6 and an error in 2.7. The +[`extension_configs`](../reference.md#extension_configs) keyword should be used +instead. See the [documentation](../reference.md#extension-configs) for a full +explanation of the current behavior. + +### HeaderId Extension Pending Deprecation + +The [HeaderId][hid] Extension is pending deprecation and will raise a +**`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 +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 (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: + +```python +ext = SomeExtension(configs={'somekey': 'somevalue'}) +``` + +That code should be updated to pass in the options directly: + +```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: + +```python +def makeExtension(configs=None): + return SomeExtension(configs=configs) +``` + +Extension authors will want to update their code to the following instead: + +```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 + +### Official Support for PyPy + +Official support for [PyPy] has been added. While Python-Markdown has most +likely worked on PyPy for some time, it is now officially supported and tested +on PyPy. + +[PyPy]: http://pypy.org/ + +### YAML Style Meta-Data + +<del>The [Meta-Data] Extension now includes optional support for [YAML] style +meta-data.</del> By default, the YAML deliminators are recognized, however, the +actual data is parsed as previously. This follows the syntax of [MultiMarkdown], +which inspired this extension. + +<del>Alternatively, if the `yaml` option is set, then the data is parsed as +YAML.</del> <ins>As the `yaml` option was buggy, it was removed in 2.6.1. It is +suggested that a preprocessor (like [docdata]) or a third party extension be +used if you want true YAML support. See [Issue #390][#390] for a full +explanation.</ins> + +[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata +[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 +listed below: + +* The extension now assigns the Table of Contents to the `toc` attribute of + the Markdown class regardless of whether a "marker" was found in the + document. Third party frameworks no longer need to insert a "marker," run + the document through Markdown, then extract the Table of Contents from the + document. + +* The Table of Contents Extension is now a "registered extension." Therefore, + when the `reset` method of the Markdown class is called, the `toc` attribute + on the Markdown class is cleared (set to an empty string). + +* When the `marker` configuration option is set to an empty string, the parser + completely skips the process of searching the document for markers. This + should save parsing time when the Table of Contents Extension is being used + only to assign ids to headers. + +* A `separator` configuration option has been added allowing users to override + the separator character used by the slugify function. + +* A `baselevel` configuration option has been added allowing users to set the + base level of headers in their documents (h1-h6). This allows the header + levels to be automatically adjusted to fit within the hierarchy of an HTML + template. + +[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 `<code>` tag as a class in the manner suggested by the +[HTML5 spec][spec] (alternate output will not be entertained) and could +potentially be used by a JavaScript library in the browser to highlight the code +block. + +[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 +benefit everyone. + +[flake8]: https://flake8.readthedocs.io/en/latest/ + +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. |