aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorWaylan Limberg <waylan.limberg@icloud.com>2014-12-30 15:33:48 -0500
committerWaylan Limberg <waylan.limberg@icloud.com>2014-12-30 15:33:48 -0500
commitfef6e285d28e25cf4acb93f0ef470fd690507cfa (patch)
tree5df9ce2b5ee3c5330accb9ff407b3edecd7566b5 /docs
parent9abd79bb787317892a1641ff2f4db332250c090c (diff)
downloadmarkdown-fef6e285d28e25cf4acb93f0ef470fd690507cfa.tar.gz
markdown-fef6e285d28e25cf4acb93f0ef470fd690507cfa.tar.bz2
markdown-fef6e285d28e25cf4acb93f0ef470fd690507cfa.zip
Added first draft of 2.6 release notes.
Diffstat (limited to 'docs')
-rw-r--r--docs/change_log.txt6
-rw-r--r--docs/extensions/toc.txt4
-rw-r--r--docs/release-2.5.txt4
-rw-r--r--docs/release-2.6.txt133
-rw-r--r--docs/siteindex.txt1
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)