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:

html = markdown.markdown(text, safe_mode=True)

Then it is recommended that you change your code to read something like this:

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:

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".

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:

html = markdown.markdown(text, [SomeExtension()])

Then it is recommended that you change it to read something like this:

html = markdown.markdown(text, extensions=[SomeExtension()])

“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:

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

Similarly, if you have used a third party extension (for example mdx_math), previously you might have called it like this:

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):

markdown.markdown(text, extensions=['mdx_math'])

Extension authors will want to update their documentation to reflect the new behavior.

See the documentation 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 keyword should be used instead. See the documentation 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 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:

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 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:

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 for more information.

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.

YAML Style Meta-Data¶

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. 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 for a full explanation.

Table of Contents Extension Refactored¶

The Table of Contents 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.

Pygments can now be disabled¶

The CodeHilite 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 (alternate output will not be entertained) and could potentially be used by a JavaScript library in the browser to highlight the code block.

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.

Various bug fixes have been made. See the commit log for a complete history of the changes.