| 1 |
title: Release Notes for v2.6 |
| 2 |
|
| 3 |
# Python-Markdown 2.6 Release Notes |
| 4 |
|
| 5 |
We are pleased to release Python-Markdown 2.6 which adds a few new features |
| 6 |
and fixes various bugs. See the list of changes below for details. |
| 7 |
|
| 8 |
Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as |
| 9 |
well as PyPy. |
| 10 |
|
| 11 |
## Backwards-incompatible Changes |
| 12 |
|
| 13 |
### `safe_mode` Deprecated |
| 14 |
|
| 15 |
Both `safe_mode` and the associated `html_replacement_text` keywords are |
| 16 |
deprecated in version 2.6 and will raise a **`DeprecationWarning`**. The |
| 17 |
`safe_mode` and `html_replacement_text` keywords will be ignored in the next |
| 18 |
release. The so-called "safe mode" was never actually "safe" which has resulted |
| 19 |
in many people having a false sense of security when using it. As an |
| 20 |
alternative, the developers of Python-Markdown recommend that any untrusted |
| 21 |
content be passed through an HTML sanitizer (like [Bleach]) after being |
| 22 |
converted to HTML by markdown. In fact, [Bleach Whitelist] provides a curated |
| 23 |
list of tags, attributes, and styles suitable for filtering user-provided HTML |
| 24 |
using bleach. |
| 25 |
|
| 26 |
If your code previously looked like this: |
| 27 |
|
| 28 |
```python |
| 29 |
html = markdown.markdown(text, safe_mode=True) |
| 30 |
``` |
| 31 |
|
| 32 |
Then it is recommended that you change your code to read something like this: |
| 33 |
|
| 34 |
```python |
| 35 |
import bleach |
| 36 |
from bleach_whitelist import markdown_tags, markdown_attrs |
| 37 |
html = bleach.clean(markdown.markdown(text), markdown_tags, markdown_attrs) |
| 38 |
``` |
| 39 |
|
| 40 |
If you are not interested in sanitizing untrusted text, but simply desire to |
| 41 |
escape raw HTML, then that can be accomplished through an extension which |
| 42 |
removes HTML parsing: |
| 43 |
|
| 44 |
```python |
| 45 |
from markdown.extensions import Extension |
| 46 |
|
| 47 |
class EscapeHtml(Extension): |
| 48 |
def extendMarkdown(self, md, md_globals): |
| 49 |
del md.preprocessors['html_block'] |
| 50 |
del md.inlinePatterns['html'] |
| 51 |
|
| 52 |
html = markdown.markdown(text, extensions=[EscapeHtml()]) |
| 53 |
``` |
| 54 |
|
| 55 |
As the HTML would not be parsed with the above Extension, then the serializer |
| 56 |
will escape the raw HTML, which is exactly what happens now when |
| 57 |
`safe_mode="escape"`. |
| 58 |
|
| 59 |
[Bleach]: https://bleach.readthedocs.io/ |
| 60 |
[Bleach Whitelist]: https://github.com/yourcelf/bleach-whitelist |
| 61 |
|
| 62 |
### Positional Arguments Deprecated |
| 63 |
|
| 64 |
Positional arguments on the `markdown.Markdown()` class are deprecated as are |
| 65 |
all except the `text` argument on the `markdown.markdown()` wrapper function. |
| 66 |
Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an |
| 67 |
error in the next release. Only keyword arguments should be used. For example, |
| 68 |
if your code previously looked like this: |
| 69 |
|
| 70 |
```python |
| 71 |
html = markdown.markdown(text, [SomeExtension()]) |
| 72 |
``` |
| 73 |
|
| 74 |
Then it is recommended that you change it to read something like this: |
| 75 |
|
| 76 |
```python |
| 77 |
html = markdown.markdown(text, extensions=[SomeExtension()]) |
| 78 |
``` |
| 79 |
|
| 80 |
!!! Note |
| 81 |
This change is being made as a result of deprecating `"safe_mode"` as the |
| 82 |
`safe_mode` argument was one of the positional arguments. When that argument |
| 83 |
is removed, the two arguments following it will no longer be at the correct |
| 84 |
position. It is recommended that you always use keywords when they are |
| 85 |
supported for this reason. |
| 86 |
|
| 87 |
### "Shortened" Extension Names Deprecated |
| 88 |
|
| 89 |
In previous versions of Python-Markdown, the built-in extensions received |
| 90 |
special status and did not require the full path to be provided. Additionally, |
| 91 |
third party extensions whose name started with `"mdx_"` received the same |
| 92 |
special treatment. This behavior is deprecated and will raise a |
| 93 |
**`DeprecationWarning`** in version 2.6 and an error in the next release. Ensure |
| 94 |
that you always use the full path to your extensions. For example, if you |
| 95 |
previously did the following: |
| 96 |
|
| 97 |
```python |
| 98 |
markdown.markdown(text, extensions=['extra']) |
| 99 |
``` |
| 100 |
|
| 101 |
You should change your code to the following: |
| 102 |
|
| 103 |
```python |
| 104 |
markdown.markdown(text, extensions=['markdown.extensions.extra']) |
| 105 |
``` |
| 106 |
|
| 107 |
The same applies to the command line: |
| 108 |
|
| 109 |
```python |
| 110 |
python -m markdown -x markdown.extensions.extra input.txt |
| 111 |
``` |
| 112 |
|
| 113 |
Similarly, if you have used a third party extension (for example `mdx_math`), |
| 114 |
previously you might have called it like this: |
| 115 |
|
| 116 |
```python |
| 117 |
markdown.markdown(text, extensions=['math']) |
| 118 |
``` |
| 119 |
|
| 120 |
As the `"mdx"` prefix will no longer be appended, you will need to change your |
| 121 |
code as follows (assuming the file `mdx_math.py` is installed at the root of |
| 122 |
your PYTHONPATH): |
| 123 |
|
| 124 |
```python |
| 125 |
markdown.markdown(text, extensions=['mdx_math']) |
| 126 |
``` |
| 127 |
|
| 128 |
Extension authors will want to update their documentation to reflect the new |
| 129 |
behavior. |
| 130 |
|
| 131 |
See the [documentation](../reference.md#extensions) for a full explanation |
| 132 |
of the current behavior. |
| 133 |
|
| 134 |
### Extension Configuration as Part of Extension Name Deprecated |
| 135 |
|
| 136 |
The previously documented method of appending the extension configuration |
| 137 |
options as a string to the extension name is deprecated and will raise a |
| 138 |
**`DeprecationWarning`** in version 2.6 and an error in 2.7. The |
| 139 |
[`extension_configs`](../reference.md#extension_configs) keyword should be used |
| 140 |
instead. See the [documentation](../reference.md#extension_configs) for a full |
| 141 |
explanation of the current behavior. |
| 142 |
|
| 143 |
### HeaderId Extension Pending Deprecation |
| 144 |
|
| 145 |
The HeaderId Extension is pending deprecation and will raise a |
| 146 |
**`PendingDeprecationWarning`** in version 2.6. The extension will be deprecated |
| 147 |
in the next release and raise an error in the release after that. Use the [Table |
| 148 |
of Contents][TOC] Extension instead, which offers most of the features of the |
| 149 |
HeaderId Extension and more (support for meta data is missing). |
| 150 |
|
| 151 |
Extension authors who have been using the `slugify` and `unique` functions |
| 152 |
defined in the HeaderId Extension should note that those functions are now |
| 153 |
defined in the Table of Contents extension and should adjust their import |
| 154 |
statements accordingly (`from markdown.extensions.toc import slugify, unique`). |
| 155 |
|
| 156 |
### The `configs` Keyword is Deprecated |
| 157 |
|
| 158 |
Positional arguments and the `configs` keyword on the |
| 159 |
`markdown.extension.Extension` class (and its subclasses) are deprecated. Each |
| 160 |
individual configuration option should be passed to the class as a keyword/value |
| 161 |
pair. For example. one might have previously initiated an extension subclass |
| 162 |
like this: |
| 163 |
|
| 164 |
```python |
| 165 |
ext = SomeExtension(configs={'somekey': 'somevalue'}) |
| 166 |
``` |
| 167 |
|
| 168 |
That code should be updated to pass in the options directly: |
| 169 |
|
| 170 |
```python |
| 171 |
ext = SomeExtension(somekey='somevalue') |
| 172 |
``` |
| 173 |
|
| 174 |
Extension authors will want to note that this affects the `makeExtension` |
| 175 |
function as well. Previously it was common for the function to be defined as |
| 176 |
follows: |
| 177 |
|
| 178 |
```python |
| 179 |
def makeExtension(configs=None): |
| 180 |
return SomeExtension(configs=configs) |
| 181 |
``` |
| 182 |
|
| 183 |
Extension authors will want to update their code to the following instead: |
| 184 |
|
| 185 |
```python |
| 186 |
def makeExtension(**kwargs): |
| 187 |
return SomeExtension(**kwargs) |
| 188 |
``` |
| 189 |
|
| 190 |
Failing to do so will result in a **`DeprecationWarning`** and will raise an |
| 191 |
error in the next release. See the [Extension API][mext] documentation for more |
| 192 |
information. |
| 193 |
|
| 194 |
In the event that an `markdown.extension.Extension` subclass overrides the |
| 195 |
`__init__` method and implements its own configuration handling, then the above |
| 196 |
may not apply. However, it is recommended that the subclass still calls the |
| 197 |
parent `__init__` method to handle configuration options like so: |
| 198 |
|
| 199 |
```python |
| 200 |
class SomeExtension(markdown.extension.Extension): |
| 201 |
def __init__(**kwargs): |
| 202 |
# Do pre-config stuff here |
| 203 |
# Set config defaults |
| 204 |
self.config = { |
| 205 |
'option1' : ['value1', 'description1'], |
| 206 |
'option2' : ['value2', 'description2'] |
| 207 |
} |
| 208 |
# Set user defined configs |
| 209 |
super(MyExtension, self).__init__(**kwargs) |
| 210 |
# Do post-config stuff here |
| 211 |
``` |
| 212 |
|
| 213 |
Note the call to `super` to get the benefits of configuration handling from the |
| 214 |
parent class. See the [documentation][config] for more information. |
| 215 |
|
| 216 |
[config]: ../extensions/api.md#configsettings |
| 217 |
[mext]: ../extensions/api.md#dot_notation |
| 218 |
|
| 219 |
## What's New in Python-Markdown 2.6 |
| 220 |
|
| 221 |
### Official Support for PyPy |
| 222 |
|
| 223 |
Official support for [PyPy] has been added. While Python-Markdown has most |
| 224 |
likely worked on PyPy for some time, it is now officially supported and tested |
| 225 |
on PyPy. |
| 226 |
|
| 227 |
[PyPy]: https://pypy.org/ |
| 228 |
|
| 229 |
### YAML Style Meta-Data |
| 230 |
|
| 231 |
<del>The [Meta-Data] Extension now includes optional support for [YAML] style |
| 232 |
meta-data.</del> By default, the YAML deliminators are recognized, however, the |
| 233 |
actual data is parsed as previously. This follows the syntax of [MultiMarkdown], |
| 234 |
which inspired this extension. |
| 235 |
|
| 236 |
<del>Alternatively, if the `yaml` option is set, then the data is parsed as |
| 237 |
YAML.</del> <ins>As the `yaml` option was buggy, it was removed in 2.6.1. It is |
| 238 |
suggested that a preprocessor (like [docdata]) or a third party extension be |
| 239 |
used if you want true YAML support. See [Issue #390][#390] for a full |
| 240 |
explanation.</ins> |
| 241 |
|
| 242 |
[MultiMarkdown]: https://fletcherpenney.net/multimarkdown/#metadata |
| 243 |
[Meta-Data]: ../extensions/meta_data.md |
| 244 |
[YAML]: https://yaml.org/ |
| 245 |
[#390]: https://github.com/Python-Markdown/markdown/issues/390 |
| 246 |
[docdata]: https://github.com/waylan/docdata |
| 247 |
|
| 248 |
### Table of Contents Extension Refactored |
| 249 |
|
| 250 |
The [Table of Contents][TOC] Extension has been refactored and some new features |
| 251 |
have been added. See the documentation for a full explanation of each feature |
| 252 |
listed below: |
| 253 |
|
| 254 |
* The extension now assigns the Table of Contents to the `toc` attribute of |
| 255 |
the Markdown class regardless of whether a "marker" was found in the |
| 256 |
document. Third party frameworks no longer need to insert a "marker," run |
| 257 |
the document through Markdown, then extract the Table of Contents from the |
| 258 |
document. |
| 259 |
|
| 260 |
* The Table of Contents Extension is now a "registered extension." Therefore, |
| 261 |
when the `reset` method of the Markdown class is called, the `toc` attribute |
| 262 |
on the Markdown class is cleared (set to an empty string). |
| 263 |
|
| 264 |
* When the `marker` configuration option is set to an empty string, the parser |
| 265 |
completely skips the process of searching the document for markers. This |
| 266 |
should save parsing time when the Table of Contents Extension is being used |
| 267 |
only to assign ids to headers. |
| 268 |
|
| 269 |
* A `separator` configuration option has been added allowing users to override |
| 270 |
the separator character used by the slugify function. |
| 271 |
|
| 272 |
* A `baselevel` configuration option has been added allowing users to set the |
| 273 |
base level of headers in their documents (h1-h6). This allows the header |
| 274 |
levels to be automatically adjusted to fit within the hierarchy of an HTML |
| 275 |
template. |
| 276 |
|
| 277 |
[TOC]: ../extensions/toc.md |
| 278 |
|
| 279 |
### Pygments can now be disabled |
| 280 |
|
| 281 |
The [CodeHilite][ch] Extension has gained a new configuration option: |
| 282 |
`use_pygments`. The option is `True` by default, however, it allows one to turn |
| 283 |
off Pygments code highlighting (set to `False`) while preserving the language |
| 284 |
detection features of the extension. Note that Pygments language guessing is not |
| 285 |
used as that would 'use Pygments'. If a language is defined for a code block, it |
| 286 |
will be assigned to the `<code>` tag as a class in the manner suggested by the |
| 287 |
[HTML5 spec][spec] (alternate output will not be entertained) and could |
| 288 |
potentially be used by a JavaScript library in the browser to highlight the code |
| 289 |
block. |
| 290 |
|
| 291 |
[ch]: ../extensions/code_hilite.md |
| 292 |
[spec]: https://www.w3.org/TR/html5/text-level-semantics.html#the-code-element |
| 293 |
|
| 294 |
### Miscellaneous |
| 295 |
|
| 296 |
Test coverage has been improved including running [flake8]. While those changes |
| 297 |
will not directly effect end users, the code is being better tested which will |
| 298 |
benefit everyone. |
| 299 |
|
| 300 |
[flake8]: https://flake8.readthedocs.io/en/latest/ |
| 301 |
|
| 302 |
Various bug fixes have been made. See the |
| 303 |
[commit log](https://github.com/Python-Markdown/markdown/commits/master) |
| 304 |
for a complete history of the changes. |