diff options
Diffstat (limited to 'docs/change_log')
| -rw-r--r-- | docs/change_log/index.md | 321 | ||||
| -rw-r--r-- | docs/change_log/release-2.0.md | 69 | ||||
| -rw-r--r-- | docs/change_log/release-2.1.md | 118 | ||||
| -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 | 304 | ||||
| -rw-r--r-- | docs/change_log/release-3.0.md | 228 | ||||
| -rw-r--r-- | docs/change_log/release-3.1.md | 48 | ||||
| -rw-r--r-- | docs/change_log/release-3.2.md | 96 | ||||
| -rw-r--r-- | docs/change_log/release-3.3.md | 109 | ||||
| -rw-r--r-- | docs/change_log/release-3.4.md | 113 |
13 files changed, 1817 insertions, 0 deletions
diff --git a/docs/change_log/index.md b/docs/change_log/index.md new file mode 100644 index 0000000..9626900 --- /dev/null +++ b/docs/change_log/index.md @@ -0,0 +1,321 @@ +title: Change Log + +Python-Markdown Change Log +========================= + +July 15, 2022: version 3.4.1 (a bug-fix release). + +* Fix an import issue with `importlib.util` (#1274). + +July 15, 2022: version 3.4 ([Notes](release-3.4.md)). + +May 5, 2022: version 3.3.7 (a bug-fix release). + +* Disallow square brackets in reference link ids (#1209). +* Retain configured `pygments_style` after first code block (#1240). +* Ensure fenced code attributes are properly escaped (#1247). + +Nov 17, 2021: version 3.3.6 (a bug-fix release). + +* Fix a dependency issue (#1195, #1196). + +Nov 16, 2021: version 3.3.5 (a bug-fix release). + +* Make the `slugify_unicode` function not remove diacritical marks (#1118). +* Fix `[toc]` detection when used with `nl2br` extension (#1160). +* Re-use compiled regex for block level checks (#1169). +* Don't process shebangs in fenced code blocks when using CodeHilite (#1156). +* Improve email address validation for Automatic Links (#1165). +* Ensure `<summary>` tags are parsed correctly (#1079). +* Support Python 3.10 (#1124). + +Feb 24, 2021: version 3.3.4 (a bug-fix release). + +* Properly parse unclosed tags in code spans (#1066). +* Properly parse processing instructions in md_in_html (#1070). +* Properly parse code spans in md_in_html (#1069). +* Preserve text immediately before an admonition (#1092). +* Simplified regex for HTML placeholders (#928) addressing (#932). +* Ensure `permalinks` and `anchorlinks` are not restricted by `toc_depth` (#1107). +* Fix corner cases with lists under admonitions (#1102). + +Oct 25, 2020: version 3.3.3 (a bug-fix release). + +* Unify all block-level tags (#1047). +* Fix issue where some empty elements would have text rendered as `None` when using `md_in_html` (#1049). +* Avoid catastrophic backtracking in `hr` regex (#1055). +* Fix `hr` HTML handling (#1053). + +Oct 19, 2020: version 3.3.2 (a bug-fix release). + +* Properly parse inline HTML in md_in_html (#1040 & #1045). +* Avoid crashing when md_in_html fails (#1040). + +Oct 12, 2020: version 3.3.1 (a bug-fix release). + +* Correctly parse raw `script` and `style` tags (#1036). +* Ensure consistent class handling by `fenced_code` and `codehilite` (#1032). + +Oct 6, 2020: version 3.3 ([Notes](release-3.3.md)). + +May 8, 2020: version 3.2.2 (a bug-fix release). + +* Add `checklinks` tox environment to ensure all links in documentation are good. +* Refactor extension API documentation (#729). +* Load entry_points (for extensions) only once using `importlib.metadata`. +* Do not double escape entities in TOC. +* Correctly report if an extension raises a `TypeError` (#939). +* Raise a `KeyError` when attempting to delete a nonexistent key from the + extension registry (#939). +* Remove import of `packaging` (or `pkg_resources` fallback) entirely. +* Remove `setuptools` as a run-time dependency (`install_required`). + +Feb 12, 2020: Released version 3.2.1 (a bug-fix release). + +* The `name` property in `toc_tokens` from the TOC extension now + escapes HTML special characters (`<`, `>`, and `&`). + +Feb 7, 2020: Released version 3.2 ([Notes](release-3.2.md)). + +May 20, 2019: Released version 3.1.1 (a bug-fix release). + +* Fixed import failure in `setup.py` when the source directory is not + on `sys.path` (#823). +* Prefer public `packaging` module to pkg_resources' private copy of + it (#825). + +Mar 25, 2019: Released version 3.1 ([Notes](release-3.1.md)). + +Sept 28, 2018: Released version 3.0.1 (a bug-fix release). + +* Brought back the `version` and `version_info` variables (#709). +* Added support for hexadecimal HTML entities (#712). + +Sept 21, 2018: Released version 3.0 ([Notes](release-3.0.md)). + +Jan 4, 2018: Released version 2.6.11 (a bug-fix release). Added a new +`BACKLINK-TITLE` option to the footnote extension so that non-English +users can provide a custom title to back links (see #610). + +Dec 7, 2017: Released version 2.6.10 (a documentation update). + +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..4f7ba75 --- /dev/null +++ b/docs/change_log/release-2.1.md @@ -0,0 +1,118 @@ +title: Release Notes for v2.1 + +Python-Markdown 2.1 Release Notes +================================= + +We are pleased to release Python-Markdown 2.1 which makes many +improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. +While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline +with other implementations, some internal improvements were made to the parser, +a few new built-in extensions were added, and HTML5 support was added. + +Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out +of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no +extra work by the end user. + +Backwards-incompatible Changes +------------------------------ + +While Python-Markdown has received only minor internal changes since the last +release, there are a few backward-incompatible changes to note: + +* Support had been dropped for Python 2.3. No guarantees are made that the + library will work in any version of Python lower than 2.4. Additionally, while + the library had been tested with Python 2.4, consider Python 2.4 support to be + depreciated. It is not likely that any future versions will continue to + support any version of Python less than 2.5. Note that Python 3.0 is not + supported due to a bug in its 2to3 tool. If you must use Python-Markdown with + Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to do a + conversion. + +* Python-Markdown previously accepted positional arguments on its class and + wrapper methods. It now expects keyword arguments. Currently, the positional + arguments should continue to work, but the solution feels hacky and may be + removed in a future version. All users are encouraged to use keyword arguments + as documented in the [Library Reference](../reference.md). + +* Past versions of Python-Markdown provided module level Global variables which + controlled the behavior of a few different aspects of the parser. Those global + variables have been replaced with attributes on the Markdown class. + Additionally, those attributes are settable as keyword arguments when + initializing a class instance. Therefore, if you were editing the global + variables (either by editing the source or by overriding them in your code), + you should now set them on the class. See the [Library + Reference](../reference.md) for the options available. + +* If you have been using the HeaderId extension to + define custom ids on headers, you will want to switch to using the new + [Attribute List](../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, 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 its 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 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..75f47fa --- /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..f60e426 --- /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.github.io/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..1f4ab23 --- /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]: https://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..519f013 --- /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.org/project/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]: https://yaml.org/ +[JSON]: https://json.org/ +[PyYAML]: https://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..f117eb8 --- /dev/null +++ b/docs/change_log/release-2.6.md @@ -0,0 +1,304 @@ +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 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`). + +### 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]: https://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]: https://fletcherpenney.net/multimarkdown/#metadata +[Meta-Data]: ../extensions/meta_data.md +[YAML]: https://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]: https://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. diff --git a/docs/change_log/release-3.0.md b/docs/change_log/release-3.0.md new file mode 100644 index 0000000..29cdc4d --- /dev/null +++ b/docs/change_log/release-3.0.md @@ -0,0 +1,228 @@ +title: Release Notes for v3.0 + +# Python-Markdown 3.0 Release Notes + +We are pleased to release Python-Markdown 3.0 which adds a few new features and +fixes various bugs and deprecates various old features. See the list of changes +below for details. + +Python-Markdown version 3.0 supports Python versions 2.7, 3.4, 3.5, 3.6, 3.7, +PyPy and PyPy3. + +## Backwards-incompatible changes + +### `enable_attributes` keyword deprecated + +The `enable_attributes` keyword is deprecated in version 3.0 and will be +ignored. Previously the keyword was `True` by default and enabled an +undocumented way to define attributes on document elements. The feature has been +removed from version 3.0. As most users did not use the undocumented feature, it +should not affect most users. For the few who did use the feature, it can be +enabled by using the [Legacy Attributes](../extensions/legacy_attrs.md) +extension. + +### `smart_emphasis` keyword and `smart_strong` extension deprecated + +The `smart_emphasis` keyword is deprecated in version 3.0 and will be ignored. +Previously the keyword was `True` by default and caused the parser to ignore +middle-word emphasis. Additionally, the optional `smart_strong` extension +provided the same behavior for strong emphasis. Both of those features are now +part of the default behavior, and the [Legacy +Emphasis](../extensions/legacy_em.md) extension is available to disable that +behavior. + +### `output_formats` simplified to `html` and `xhtml`. + +The `output_formats` keyword now only accepts two options: `html` and `xhtml` +Note that if `(x)html1`, `(x)html4` or `(x)html5` are passed in, the number is +stripped and ignored. + +### `safe_mode` and `html_replacement_text` keywords deprecated + +Both `safe_mode` and the associated `html_replacement_text` keywords are +deprecated in version 3.0 and will be ignored. 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.preprocessors.deregister('html_block') + md.inlinePatterns.deregister('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 happened in previous versions +with `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 an error. 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. + +### Extension name behavior has changed + +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 is no longer the case. + +Support has been added for extensions to define an [entry +point](../extensions/api.md#entry_point). An entry point is a string name which +can be used to point to an `Extension` class. The built-in extensions now have +entry points which match the old short names. And any third-party extensions +which define entry points can now get the same behavior. See the documentation +for each specific extension to find the assigned name. + +If an extension does not define an entry point, then the full path to the +extension must be used. 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 an error. +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 deprecated + +The HeaderId Extension is deprecated and will raise an error if specified. Use +the [Table of Contents](../extensions/toc.md) 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`). + +### Homegrown `OrderedDict` has been replaced with a purpose-built `Registry` + +All processors and patterns now get "registered" to a +[Registry](../extensions/api.md#registry). A backwards compatible shim is +included so that existing simple extensions should continue to work. +A `DeprecationWarning` will be raised for any code which calls the old API. + +### Markdown class instance references. + +Previously, instances of the `Markdown` class were represented as any one of +`md`, `md_instance`, or `markdown`. This inconsistency made it difficult when +developing extensions, or just maintaining the existing code. Now, all instances +are consistently represented as `md`. + +The old attributes on class instances still exist, but raise a +`DeprecationWarning` when accessed. Also on classes where the instance was +optional, the attribute always exists now and is simply `None` if no instance +was provided (previously the attribute would not exist). + +### `markdown.util.isBlockLevel` deprecated + +The `markdown.util.isBlockLevel` function is deprecated and will raise a +`DeprecationWarning`. Instead, extensions should use the `isBlockLevel` method +of the `Markdown` class instance. Additionally, a list of block level elements +is defined in the `block_level_elements` attribute of the `Markdown` class which +extensions can access to alter the list of elements which are treated as block +level elements. + +### `md_globals` keyword deprecated from extension API + +Previously, the `extendMarkdown` method of a `markdown.extensions.Extension` +subclasses accepted an `md_globals` keyword, which contained the value returned +by Python's `globals()` built-in function. As all of the configuration is now +held within the `Markdown` class instance, access to the globals is no longer +necessary and any extensions which expect the keyword will raise a +`DeprecationWarning`. A future release will raise an error. + +### `markdown.version` and `markdown.version_info` deprecated + +Historically, version numbers were acquired via the attributes +`markdown.version` and `markdown.version_info`. Moving forward, a more +standardized approach is being followed and versions are acquired via the +`markdown.__version__` and `markdown.__version_info__` attributes. The legacy +attributes are still available to allow distinguishing versions between the +legacy Markdown 2.0 series and the Markdown 3.0 series, but in the future the +legacy attributes will be removed. + +### Added new, more flexible `InlineProcessor` class + +A new `InlineProcessor` class handles inline processing much better and allows +for more flexibility. The new `InlineProcessor` classes no longer utilize +unnecessary pretext and post-text captures. New class can accept the buffer that +is being worked on and manually process the text without regular expressions and +return new replacement bounds. This helps us to handle links in a better way and +handle nested brackets and logic that is too much for regular expression. + +## New features + +The following new features have been included in the release: + +* A new [testing framework](../test_tools.md) is included as a part of the + Markdown library, which can also be used by third party extensions. + +* A new `toc_depth` parameter has been added to the + [Table of Contents Extension](../extensions/toc.md). + +* A new `toc_tokens` attribute has been added to the Markdown class by the + [Table of Contents Extension](../extensions/toc.md), which contains the raw + tokens used to build the Table of Contents. Users can use this to build their + own custom Table of Contents rather than needing to parse the HTML available + on the `toc` attribute of the Markdown class. + +* When the [Table of Contents Extension](../extensions/toc.md) is used in + conjunction with the [Attribute Lists Extension](../extensions/attr_list.md) + and a `data-toc-label` attribute is defined on a header, the content of the + `data-toc-label` attribute is now used as the content of the Table of Contents + item for that header. + +* Additional CSS class names can be appended to + [Admonitions](../extensions/admonition.md). diff --git a/docs/change_log/release-3.1.md b/docs/change_log/release-3.1.md new file mode 100644 index 0000000..b05cd23 --- /dev/null +++ b/docs/change_log/release-3.1.md @@ -0,0 +1,48 @@ +title: Release Notes for v3.1 + +# Python-Markdown 3.1 Release Notes + +Python-Markdown version 3.1 supports Python versions 2.7, 3.5, 3.6, 3.7, +PyPy and PyPy3. + +## Backwards-incompatible changes + +### `markdown.version` and `markdown.version_info` deprecated + +Historically, version numbers were acquired via the attributes +`markdown.version` and `markdown.version_info`. As of 3.0, a more standardized +approach is being followed and versions are acquired via the +`markdown.__version__` and `markdown.__version_info__` attributes. As of 3.1 +the legacy attributes will raise a `DeprecationWarning` if they are accessed. In +a future release the legacy attributes will be removed. + +## New features + +The following new features have been included in the release: + +* A [Contributing Guide](../contributing.md) has been added (#732). + +* A new configuration option to set the footnote separator has been added. Also, + the `rel` and `rev` attributes have been removed from footnotes as they are + not valid in HTML5. The `refs` and `backrefs` classes already exist and + serve the same purpose (#723). + +* A new option for `toc_depth` to set not only the bottom section level, + but also the top section level. A string consisting of two digits + separated by a hyphen in between (`"2-5"`), defines the top (`t`) and the + bottom (`b`) (`<ht>..<hb>`). A single integer still defines the bottom + section level (`<h1>..<hb>`) only. (#787). + +## Bug fixes + +The following bug fixes are included in the 3.1 release: + +* Update CLI to support PyYAML 5.1. +* Overlapping raw HTML matches no longer leave placeholders behind (#458). +* Emphasis patterns now recognize newline characters as whitespace (#783). +* Version format had been updated to be PEP 440 compliant (#736). +* Block level elements are defined per instance, not as class attributes + (#731). +* Double escaping of block code has been eliminated (#725). +* Problems with newlines in references has been fixed (#742). +* Escaped `#` are now handled in header syntax (#762). diff --git a/docs/change_log/release-3.2.md b/docs/change_log/release-3.2.md new file mode 100644 index 0000000..f9452cc --- /dev/null +++ b/docs/change_log/release-3.2.md @@ -0,0 +1,96 @@ +title: Release Notes for v3.2 + +# Python-Markdown 3.2 Release Notes + +Python-Markdown version 3.2 supports Python versions 3.5, 3.6, 3.7, 3.8, and +PyPy3. + +## Backwards-incompatible changes + +### Drop support for Python 2.7 + +Python 2.7 reaches end-of-life on 2020-01-01 and Python-Markdown 3.2 has dropped +support for it. Please upgrade to Python 3, or use Python-Markdown 3.1. + +### `em` and `strong` inline processor changes + +In order to fix issue #792, `em`/`strong` inline processors were refactored. This +translated into removing many of the existing inline processors that handled this +logic: + +* `em_strong` +* `strong` +* `emphasis` +* `strong2` +* `emphasis` + +These processors were replaced with two new ones: + +* `em_strong` +* `em_strong2` + +The [`legacy_em`](../extensions/legacy_em.md) extension was also modified with new, +refactored logic and simply overrides the `em_strong2` inline processor. + +### CodeHilite now always wraps with `<code>` tags + +Before, the HTML generated by CodeHilite looked like: +- `<pre><code>foo = 'bar'</code></pre>` if you **were not** using Pygments. +- `<pre>foo = 'bar'</pre>` if you **were** using Pygments. + +To make the cases more consistent (and adhere to many Markdown specifications and +HTML code block markup suggestions), CodeHilite will now always additionally wrap +code with `<code>` tags. See #862 for more details. + +This change does not alter the Python-Markdown API, but users relying on the old +markup will find their output now changed. + +Internally, this change relies on the Pygments 2.4, so you must be using at least +that version to see this effect. Users with earlier Pygments versions will +continue to see the old behavior. + +### `markdown.util.etree` deprecated + +Previously, Python-Markdown was using either the `xml.etree.cElementTree` module +or the `xml.etree.ElementTree` module, based on their availability. In modern +Python versions, the former is a deprecated alias for the latter. Thus, the +compatibility layer is deprecated and extensions are advised to use +`xml.etree.ElementTree` directly. Importing `markdown.util.etree` will raise +a `DeprecationWarning` beginning in version 3.2 and may be removed in a future +release. + +Therefore, extension developers are encouraged to replace +`from markdown.util import etree` with +`import xml.etree.ElementTree as etree` in their code. + +## New features + +The following new features have been included in the release: + +* Some new configuration options have been added to the [toc](../extensions/toc.md) + extension: + + * The `anchorlink_class` and `permalink_class` options allow class(es) to be + assigned to the `anchorlink` and `permalink` respectively. This allows using + icon fonts from CSS for the links. Therefore, an empty string passed to + `permalink` now generates an empty `permalink`. Previously no `permalink` + would have been generated. (#776) + + * The `permalink_title` option allows the title attribute of a `permalink` to be + set to something other than the default English string `Permanent link`. (#877) + +* Document thread safety (#812). + +* Markdown parsing in HTML has been exposed via a separate extension called + [`md_in_html`](../extensions/md_in_html.md). + +* Add support for Python 3.8. + +## Bug fixes + +The following bug fixes are included in the 3.2 release: + +* HTML tag placeholders are no longer included in `.toc_tokens` (#899). +* Unescape backslash-escaped characters in TOC ids (#864). +* Refactor bold and italic logic in order to solve complex nesting issues (#792). +* Always wrap CodeHilite code in `code` tags (#862). diff --git a/docs/change_log/release-3.3.md b/docs/change_log/release-3.3.md new file mode 100644 index 0000000..79e22b2 --- /dev/null +++ b/docs/change_log/release-3.3.md @@ -0,0 +1,109 @@ +title: Release Notes for v3.3 + +# Python-Markdown 3.3 Release Notes + +Python-Markdown version 3.3 supports Python versions 3.6, 3.7, 3.8, 3.9 and PyPy3. + +## Backwards-incompatible changes + +### The prefix `language-` is now prepended to all language classes by default on code blocks. + +The [HTML5 spec][spec] recommends that the class defining the language of a code block be prefixed with `language-`. +Therefore, by default, both the [fenced_code] and [codehilite] extensions now prepend the prefix when code +highlighting is disabled. + +If you have previously been including the prefix manually in your fenced code blocks, then you will not want a second +instance of the prefix. Similarly, if you are using a third party syntax highlighting tool which does not recognize +the prefix, or requires a different prefix, then you will want to redefine the prefix globally using the `lang_prefix` +configuration option of either the `fenced_code` or `codehilite` extensions. + +For example, to configure `fenced_code` to not apply any prefix (the previous behavior), set the option to an empty string: + +```python +from markdown.extensions.fenced_code import FencedCodeExtension + +markdown.markdown(src, extensions=[FencedCodeExtension(lang_prefix='')]) +``` + +!!! note + When code highlighting is [enabled], the output from Pygments is used unaltered. Currently, Pygments does not + provide an option to include the language class in the output, let alone prefix it. Therefore, any language prefix + is only applied when syntax highlighting is disabled. + +### Attribute Lists are more strict (#898). + +Empty curly braces are now completely ignored by the [Attribute List] extension. Previously, the extension would +recognize them as attribute lists and remove them from the document. Therefore, it is no longer necessary to backslash +escape a set of curly braces which are empty or only contain whitespace. + +Despite not being documented, previously an attribute list could be defined anywhere within a table cell and get +applied to the cell (`<td>` element). Now the attribute list must be defined at the end of the cell content and must +be separated from the rest of the content by at least one space. This makes it easy to differentiate between attribute +lists defined on inline elements within a cell and the attribute list for the cell itself. It is also more consistent +with how attribute lists are defined on other types of elements. + +The extension has also added support for defining attribute lists on table header cells (`<th>` elements) in the same +manner as data cells (`<td>` elements). + +In addition, the documentation for the extensions received an overhaul. The features (#987) and limitations (#965) of the extension are now fully documented. + +## New features + +The following new features have been included in the 3.3 release: + +* All Pygments' options are now available for syntax highlighting (#816). + - The [Codehilite](../extensions/code_hilite.md) extension now accepts any options + which Pygments supports as global configuration settings on the extension. + - [Fenced Code Blocks](../extensions/fenced_code_blocks.md) will accept any of the + same options on individual code blocks. + - Any of the previously supported aliases to Pygments' options continue to be + supported at this time. However, it is recommended that the Pygments option names + be used directly to ensure continued compatibility in the future. + +* [Fenced Code Blocks](../extensions/fenced_code_blocks.md) now work with + [Attribute Lists](../extensions/attr_list.md) when syntax highlighting is disabled. + Any random HTML attribute can be defined and set on the `<code>` tag of fenced code + blocks when the `attr_list` extension is enabled (#816). + +* The HTML parser has been completely replaced. The new HTML parser is built on Python's + [html.parser.HTMLParser](https://docs.python.org/3/library/html.parser.html), which + alleviates various bugs and simplify maintenance of the code (#803, #830). + +* The [Markdown in HTML](../extensions/md_in_html.md) extension has been rebuilt on the + new HTML Parser, which drastically simplifies it. Note that raw HTML elements with a + `markdown` attribute defined are now converted to ElementTree Elements and are rendered + by the serializer. Various bugs have been fixed (#803, #595, #780, and #1012). + +* Link reference parsing, abbreviation reference parsing and footnote reference parsing + has all been moved from `preprocessors` to `blockprocessors`, which allows them to be + nested within other block level elements. Specifically, this change was necessary to + maintain the current behavior in the rebuilt Markdown in HTML extension. A few random + edge-case bugs (see the included tests) were resolved in the process (#803). + +* An alternate function `markdown.extensions.headerid.slugify_unicode` has been included + with the [Table of Contents](../extensions/toc.md) extension which supports Unicode + characters in table of contents slugs. The old `markdown.extensions.headerid.slugify` + method which removes non-ASCII characters remains the default. Import and pass + `markdown.extensions.headerid.slugify_unicode` to the `slugify` configuration option + to use the new behavior. + +* Support was added for Python 3.9 and dropped for Python 3.5. + +## Bug fixes + +The following bug fixes are included in the 3.3 release: + +* Document how to pass configuration options to Extra (#1019). +* Fix HR which follows strong em (#897). +* Support short reference image links (#894). +* Avoid a `RecursionError` from deeply nested blockquotes (#799). +* Fix issues with complex emphasis (#979). +* Fix unescaping of HTML characters `<>` in CodeHilite (#990). +* Fix complex scenarios involving lists and admonitions (#1004). +* Fix complex scenarios with nested ordered and unordered lists in a definition list (#918). + +[spec]: https://www.w3.org/TR/html5/text-level-semantics.html#the-code-element +[fenced_code]: ../extensions/fenced_code_blocks.md +[codehilite]: ../extensions/code_hilite.md +[enabled]: ../extensions/fenced_code_blocks.md#enabling-syntax-highlighting +[Attribute List]: ../extensions/attr_list.md diff --git a/docs/change_log/release-3.4.md b/docs/change_log/release-3.4.md new file mode 100644 index 0000000..bfa8075 --- /dev/null +++ b/docs/change_log/release-3.4.md @@ -0,0 +1,113 @@ +title: Release Notes for v3.4 + +# Python-Markdown 3.4 Release Notes + +Python-Markdown version 3.4 supports Python versions 3.7, 3.8, 3.9, 3.10 and +PyPy3. + +## Backwards-incompatible changes + +### The `tables` extension now uses a `style` attribute instead of an `align` attribute for alignment. + +The [HTML4 spec][spec4] specifically deprecates the use of the `align` attribute +and it does not appear at all in the [HTML5 spec][spec5]. Therefore, by default, +the [tables] extension will now use the `style` attribute (setting just the +`text-align` property) in `td` and `th` blocks. + +[spec4]: https://www.w3.org/TR/html4/present/graphics.html#h-15.1.2 +[spec5]: https://www.w3.org/TR/html53/tabular-data.html#attributes-common-to-td-and-th-elements +[tables]: ../extensions/tables.md + +The former behavior is available by setting the `use_align_attribute` +configuration option to `True` when enabling the extension. + +For example, to configure the old `align` behavior: + +```python +from markdown.extensions.tables import TableExtension + +markdown.markdown(src, extensions=[TableExtension(use_align_attribute=True)]) +``` + +### Backslash unescaping moved to Treeprocessor (#1131). + +Unescaping backslash escapes has been moved to a Treeprocessor, which enables +proper HTML escaping during serialization. However, it is recognized that +various third-party extensions may be calling the old class at +`postprocessors.UnescapePostprocessor`. Therefore, the old class remains in the +code base, but has been deprecated and will be removed in a future release. The +new class `treeprocessors.UnescapeTreeprocessor` should be used instead. + +### Previously deprecated objects have been removed + +Various objects were deprecated in version 3.0 and began raising deprecation +warnings (see the [version 3.0 release notes] for details). Any of those objects +which remained in version 3.3 have been removed from the code base in version 3.4 +and will now raise errors. The relevant objects are listed below. + +[version 3.0 release notes]: release-3.0.md + +| Deprecated Object | Replacement Object | +|----------------------------------------|-------------------------------------| +| `markdown.version` | `markdown.__version__` | +| `markdown.version_info` | `markdown.__version_info__` | +| `markdown.util.etree` | `xml.etree.ElementTree` | +| `markdown.util.string_type` | `str` | +| `markdown.util.text_type` | `str` | +| `markdown.util.int2str` | `chr` | +| `markdown.util.iterrange` | `range` | +| `markdown.util.isBlockLevel` | `markdown.Markdown().is_block_level`| +| `markdown.util.Processor().markdown` | `markdown.util.Processor().md` | +| `markdown.util.Registry().__setitem__` | `markdown.util.Registry().register` | +| `markdown.util.Registry().__delitem__` |`markdown.util.Registry().deregister`| +| `markdown.util.Registry().add` | `markdown.util.Registry().register` | + +In addition, the `md_globals` parameter of +`Markdown.extensions.Extension.extendMarkdown()` is no longer recognized as a +valid parameter and will raise an error if provided. + +## New features + +The following new features have been included in the 3.4 release: + + +* Some new configuration options have been added to the + [footnotes](../extensions/footnotes.md) extension (#1218): + + * Small refactor of the `BACKLINK_TITLE` option; The use of `format()` + instead of "old" `%d` formatter allows one to specify text without the + need to have the number of the footnote in it (like footnotes on + Wikipedia for example). The modification is backward compatible so no + configuration change is required. + + * Addition of a new option `SUPERSCRIPT_TEXT` that allows one to specify a + custom placeholder for the footnote itself in the text. + Ex: `[{}]` will give `<sup>[1]</sup>`, `({})` will give `<sup>(1)</sup>`, + or by default, the current behavior: `<sup>1</sup>`. + +* The [Table of Contents](../extensions/toc.md) extension now accepts a + `toc_class` parameter which can be used to set the CSS class(es) on the + `<div>` that contains the Table of Contents (#1224). + +* The CodeHilite extension now supports a `pygments_formatter` option that can + be set to a custom formatter class (#1187). + + - If `pygments_formatter` is set to a string (ex: `'html'`), Pygments' + default formatter by that name is used. + - If `pygments_formatter` is set to a formatter class (or any callable + which returns a formatter instance), then an instance of that class is + used. + + The formatter class is now passed an additional option, `lang_str`, to + denote the language of the code block (#1258). While Pygments' built-in + formatters will ignore the option, a custom formatter assigned to the + `pygments_formatter` option can make use of the `lang_str` to include the + code block's language in the output. + +## Bug fixes + +The following bug fixes are included in the 3.4 release: + +* Extension entry-points are only loaded if needed (#1216). +* Added additional checks to the `<pre><code>` handling of + `PrettifyTreeprocessor` (#1261, #1263). |