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.

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()` are deprecated as are
  all except the `text` argument on the `markdown.markdown()` wrapper function.
  Using positional argument 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
  previosuly 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` argumnet 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 recomended that you always use keywords when they are supported
		for this reason.

* In previous versions of Python-Markdown, the builtin extensions received
  special status and did not require the full path to be provided. Additionaly,
  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 explaination
    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 explaination of the current behavior.

What's New in Python-Markdown 2.6
---------------------------------

*   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 [TOC] Extension has been refactored. Significantly, the extension now
    assigns the Table of Contents to the `toc` attrbibute 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.
    
    Additionaly, 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).

[TOC]: extensions/toc.html

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

[fake8]: 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.