diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/change_log.txt | 6 | ||||
| -rw-r--r-- | docs/extensions/toc.txt | 4 | ||||
| -rw-r--r-- | docs/release-2.5.txt | 4 | ||||
| -rw-r--r-- | docs/release-2.6.txt | 133 | ||||
| -rw-r--r-- | docs/siteindex.txt | 1 |
5 files changed, 142 insertions, 6 deletions
diff --git a/docs/change_log.txt b/docs/change_log.txt index a2aa24b..e63c48a 100644 --- a/docs/change_log.txt +++ b/docs/change_log.txt @@ -1,12 +1,14 @@ title: Change Log prev_title: Test Suite prev_url: test_suite.html -next_title: Release Notes for v2.5 -next_url: release-2.5.html +next_title: Release Notes for v2.6 +next_url: release-2.6.html Python-Markdown Changelog ========================= +____________: Released version 2.6 ([Notes](release-2.6.html)). + Nov 19, 2014: Released version 2.5.2 (a bugfix release). Sept 26, 2014: Released version 2.5.1 (a bugfix release). diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt index 1d83df2..56a8ee0 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.txt @@ -56,8 +56,8 @@ The following options are provided to configure the output: Text to find and replace with the Table of Contents. Defaults to `[TOC]`. - If a `marker` is not found in the document, then the Table of Contents is - available as an attribute of the Markdown class. This allows one to insert + Regardless of whether a `marker` is found in the document, the Table of Contents is + also available as an attribute (`toc`) of the Markdown class. This allows one to insert the Table of Contents elsewhere in their page template. For example: >>> text = ''' diff --git a/docs/release-2.5.txt b/docs/release-2.5.txt index 250332e..5b3e5f7 100644 --- a/docs/release-2.5.txt +++ b/docs/release-2.5.txt @@ -1,6 +1,6 @@ title: Release Notes for v2.5 -prev_title: Change Log -prev_url: change_log.html +prev_title: Release Notes for v2.6 +prev_url: release-2.6.html next_title: Release Notes for v2.4 next_url: release-2.4.html diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt new file mode 100644 index 0000000..0724700 --- /dev/null +++ b/docs/release-2.6.txt @@ -0,0 +1,133 @@ +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, same_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. diff --git a/docs/siteindex.txt b/docs/siteindex.txt index 3d1e22e..19072d8 100644 --- a/docs/siteindex.txt +++ b/docs/siteindex.txt @@ -66,6 +66,7 @@ Table of Contents * [Syntax Test Config Settings](test_suite.html#syntax-test-config-settings) * [Unit Tests](test_suite.html#unit-tests) * [Change Log](change_log.html) + * [Release Notes for v.2.6](release-2.6.html) * [Release Notes for v.2.5](release-2.5.html) * [Release Notes for v.2.4](release-2.4.html) * [Release Notes for v.2.3](release-2.3.html) |