title: Release Notes for v2.6 prev_title: Change Log prev_url: change_log.html next_title: Release Notes for v2.5 next_url: release-2.5.html Python-Markdown 2.6 Release Notes ================================= 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 ------------------------------ * Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and `html_replacement_text` keywords will be ignored in version 2.7. The so-called "safe mode" was never actually "safe" which has resulted in many people having a false sense of security when using it. As an alternative, the developers of Python-Markdown recommend that any untrusted content be passed through an HTML sanitizer (like [Bleach]) after being converted to HTML by markdown. If your code previously looked like this: html = markdown.markdown(text, safe_mode=True) Then it is recommended that you change your code to read something like this: import bleach html = bleach.clean(markdown.markdown(text)) 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 searializer will escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`. [Bleach]: http://bleach.readthedocs.org/ * Positional arguments on the `markdown.Markdown()` class are deprecated as are all except the `text` argument on the `markdown.markdown()` wrapper function. Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an error in version 2.7. Only keyword arguments should be used. For example, if your code previously looked like this: html = markdown.markdown(text, [SomeExtension()]) Then it is recommended that you change it to read something like this: html = markdown.markdown(text, extensions=[SomeExtension()]) !!! Note This change is being made as a result of deprecating `"safe_mode"` as the `safe_mode` argument was one of the positional arguments. When that argument is removed, the two arguments following it will no longer be at the correct 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 is deprecated and will raise a **`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you always use the full path to your extensions. For example, if you previously did the following: 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.html#extensions) for a full explanation of the current behavior. * The previously documented method of appending the extension configs as a string to the extension name is deprecated and will raise a **`DeprecationWarning`** in version 2.6 and an error in 2.7. The [extension_configs](reference.html#extension_configs) keyword should be used instead. See the [documentation](reference.html#extension-configs) for a full explanation of the current behavior. * The [HeaderId][hid] Extension is pending deprecation and will raise a **`PendingDeprecationWarning`** in version 2.6. The extension will be deprecated in version 2.7 and raise an error in version 2.8. Use the [Table of Contents][TOC] Extension instead, which offers most of the features of the HeaderId Extension and more (support for meta data is missing). Extension authors who have been using the `slugify` and `unique` functions defined in the HeaderId Extension should note that those functions are now defined in the Table of Contents extension and should adjust their import statements accordingly (`from markdown.extensions.toc import slugify, unique`). [hid]: extensions/header_id.html * Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class (and its subclasses) are deprecated. Each individual config option should be passed to the class as a keyword/value pair. For example. one might have previously initiated an extension subclass like this: ext = SomeExtension(configs={'somekey': 'somevalue'}) That code should be updated to pass in the options directly: 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: def makeExtension(configs=None): return SomeExtension(configs=configs) Extension authors will want to update their code to the following instead: def makeExtension(**kwargs): return SomeExtension(**kwargs) Failing to do so will result in a DeprecationWarning and will raise an error in the next release. See the [Extension API][mext] documentation for more information. In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method and implements its own config handling, then the above may not apply. However, it is recommended that the subclass still calls the parent `__init__` method to handle configs like so: class SomeExtension(markdown.extension.Extension): def __init__(**kwargs): # Do pre-config stuff here # Set config defaults self.config = { 'option1' : ['value1', 'description1'], 'option2' : ['value2', 'description2'] } # Set user defined configs super(MyExtension, self).__init__(**kwargs) # Do post-config stuff here Note the call to `super` to get the benefits of config handling from the parent class. See the [documentation][config] for more information. [config]: extensions/api.html#configsettings [mext]: extensions/api.html#makeextension What's New in Python-Markdown 2.6 --------------------------------- * Official support for [PyPy] has been added. While Python-Markdown has most likely worked on PyPy for some time, it is now officially supported and tested on PyPy. [PyPy]: http://pypy.org/ * The [Meta-Data] Extension now includes optional support for [YAML] style meta-data. By default, the YAML deliminators are recognized, however, the actual data is parsed as previously. This follows the syntax of [MultiMarkdown], which inspired this extension. Alternatively, if the `yaml` option is set, then the data is parsed as YAML. [MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata [Meta-Data]: extensions/meta_data.html [YAML]: http://yaml.org/ * The [Table fo 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 TOC from the document. * The TOC 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` config 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 TOC Extension is being used only to assign ids to headers. * A `separator` config option has been added allowing users to override the separator character used by the slugify function. * A `baselevel` config 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.html * The [CodeHilite][ch] Extension has gained a new config 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 detection is not used as that would 'use Pygments`. If a language is defined for a code block, it will be assigned to the `` tag as a class in the manner suggested by the [HTML5 spec][spec] (alternate output will not be entertained) and might be used by a JavaScript library in the browser to highlight the code block. [ch]: extensions/code_hilite.html [spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element * 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]: http://flake8.readthedocs.org/en/latest/ * Various bug fixes have been made. See the [commit log](https://github.com/waylan/Python-Markdown/commits/master) for a complete history of the changes.