| 1 |
title: Release Notes for v2.1 |
| 2 |
|
| 3 |
Python-Markdown 2.1 Release Notes |
| 4 |
================================= |
| 5 |
|
| 6 |
We are pleased to release Python-Markdown 2.1 which makes many |
| 7 |
improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. |
| 8 |
While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline |
| 9 |
with other implementations, some internal improvements were made to the parser, |
| 10 |
a few new built-in extensions were added, and HTML5 support was added. |
| 11 |
|
| 12 |
Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out |
| 13 |
of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no |
| 14 |
extra work by the end user. |
| 15 |
|
| 16 |
Backwards-incompatible Changes |
| 17 |
------------------------------ |
| 18 |
|
| 19 |
While Python-Markdown has received only minor internal changes since the last |
| 20 |
release, there are a few backward-incompatible changes to note: |
| 21 |
|
| 22 |
* Support had been dropped for Python 2.3. No guarantees are made that the |
| 23 |
library will work in any version of Python lower than 2.4. Additionally, while |
| 24 |
the library had been tested with Python 2.4, consider Python 2.4 support to be |
| 25 |
depreciated. It is not likely that any future versions will continue to |
| 26 |
support any version of Python less than 2.5. Note that Python 3.0 is not |
| 27 |
supported due to a bug in its 2to3 tool. If you must use Python-Markdown with |
| 28 |
Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to do a |
| 29 |
conversion. |
| 30 |
|
| 31 |
* Python-Markdown previously accepted positional arguments on its class and |
| 32 |
wrapper methods. It now expects keyword arguments. Currently, the positional |
| 33 |
arguments should continue to work, but the solution feels hacky and may be |
| 34 |
removed in a future version. All users are encouraged to use keyword arguments |
| 35 |
as documented in the [Library Reference](../reference.md). |
| 36 |
|
| 37 |
* Past versions of Python-Markdown provided module level Global variables which |
| 38 |
controlled the behavior of a few different aspects of the parser. Those global |
| 39 |
variables have been replaced with attributes on the Markdown class. |
| 40 |
Additionally, those attributes are settable as keyword arguments when |
| 41 |
initializing a class instance. Therefore, if you were editing the global |
| 42 |
variables (either by editing the source or by overriding them in your code), |
| 43 |
you should now set them on the class. See the [Library |
| 44 |
Reference](../reference.md) for the options available. |
| 45 |
|
| 46 |
* If you have been using the HeaderId extension to |
| 47 |
define custom ids on headers, you will want to switch to using the new |
| 48 |
[Attribute List](../extensions/attr_list.md) extension. The HeaderId extension |
| 49 |
now only auto-generates ids on headers which have not already had ids defined. |
| 50 |
Note that the [Extra](../extensions/extra.md) extension has been switched to |
| 51 |
use Attribute Lists instead of HeaderId as it did previously. |
| 52 |
|
| 53 |
* Some code was moved into the `markdown.util` namespace which was previously in |
| 54 |
the `markdown` namespace. Extension authors may need to adjust a few import |
| 55 |
statements in their extensions to work with the changes. |
| 56 |
|
| 57 |
* The command line script name was changed to `markdown_py`. The previous name |
| 58 |
(`markdown`) was conflicting with people (and Linux package systems) who also |
| 59 |
had markdown.pl installed on there system as markdown.pl's command line script |
| 60 |
was also named `markdown`. Be aware that installing Python-Markdown 2.1 will |
| 61 |
not remove the old versions of the script with different names. You may want |
| 62 |
to remove them yourself as they are unlikely to work properly. |
| 63 |
|
| 64 |
What's New in Python-Markdown 2.1 |
| 65 |
--------------------------------- |
| 66 |
|
| 67 |
Three new extensions were added. [Attribute Lists](../extensions/attr_list.md), |
| 68 |
which was inspired by Maruku's feature of the same name, [Newline to |
| 69 |
Break](../extensions/nl2br.md), which was inspired by GitHub Flavored Markdown, |
| 70 |
and Smart Strong, which fills a hole in the Extra extension. |
| 71 |
|
| 72 |
HTML5 is now supported. All this really means is that new block level elements |
| 73 |
introduced in the HTML5 spec are now properly recognized as raw HTML. As |
| 74 |
valid HTML5 can consist of either HTML4 or XHTML1, there is no need to add a |
| 75 |
new HTML5 serializers. That said, `html5` and `xhtml5` have been added as |
| 76 |
aliases of the `html4` and `xhtml1` serializers respectively. |
| 77 |
|
| 78 |
An XHTML serializer has been added. Previously, ElementTree's XML serializer |
| 79 |
was being used for XHTML output. With the new serializer we are able to avoid |
| 80 |
more invalid output like empty elements (i.e., `<p />`) which can choke |
| 81 |
browsers. |
| 82 |
|
| 83 |
Improved support for Python 3.x. Now when running `setupy.py install` in |
| 84 |
Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 |
| 85 |
is not supported due to a bug in its 2to3 tool. If you must use Python-Markdown |
| 86 |
with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to |
| 87 |
do a conversion. |
| 88 |
|
| 89 |
Methods on instances of the Markdown class that do not return results can now |
| 90 |
be changed allowing one to do `md.reset().convert(moretext)`. |
| 91 |
|
| 92 |
The Markdown class was refactored so that a subclass could define its own |
| 93 |
`build_parser` method which would build a completely different parser. In |
| 94 |
other words, one could use the basic machinery in the markdown library to |
| 95 |
build a parser of a different markup language without the overhead of building |
| 96 |
the markdown parser and throwing it away. |
| 97 |
|
| 98 |
Import statements within markdown have been improved so that third party |
| 99 |
libraries can embed the markdown library if they desire (licensing permitting). |
| 100 |
|
| 101 |
Added support for Python's `-m` command line option. You can run the markdown |
| 102 |
package as a command line script. Do `python -m markdown [options] [args]`. |
| 103 |
Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 |
| 104 |
require you to call the module directly (`markdown.__main__`) rather than |
| 105 |
the package (`markdown`). This does not work in Python 2.4. |
| 106 |
|
| 107 |
The command line script has been renamed to `markdown_py` which avoids all the |
| 108 |
various problems we had with previous names. Also improved the command line |
| 109 |
script to accept input on `stdin`. |
| 110 |
|
| 111 |
The testing framework has been completely rebuilt using the Nose testing |
| 112 |
framework. This provides a number of benefits including the ability to better |
| 113 |
test the built-in extensions and other options available to change the parsing |
| 114 |
behavior. See the Test Suite documentation for details. |
| 115 |
|
| 116 |
Various bug fixes have been made, which are too numerous to list here. See the |
| 117 |
[commit log](https://github.com/Python-Markdown/markdown/commits/master) for a |
| 118 |
complete history of the changes. |