Skip to content

Commit fef6e28

Browse files
waylanwaylan
committed
Added first draft of 2.6 release notes.
1 parent 9abd79b commit fef6e28

File tree

5 files changed

+142
-6
lines changed

5 files changed

+142
-6
lines changed

‎docs/change_log.txt‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
title: Change Log
22
prev_title: Test Suite
33
prev_url: test_suite.html
4-
next_title: Release Notes for v2.5
5-
next_url: release-2.5.html
4+
next_title: Release Notes for v2.6
5+
next_url: release-2.6.html
66

77
Python-Markdown Changelog
88
=========================
99

10+
____________: Released version 2.6 ([Notes](release-2.6.html)).
11+
1012
Nov 19, 2014: Released version 2.5.2 (a bugfix release).
1113

1214
Sept 26, 2014: Released version 2.5.1 (a bugfix release).

‎docs/extensions/toc.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,8 @@ The following options are provided to configure the output:
5656
Text to find and replace with the Table of Contents. Defaults
5757
to `[TOC]`.
5858

59-
If a `marker` is not found in the document, then the Table of Contents is
60-
available as an attribute of the Markdown class. This allows one to insert
59+
Regardless of whether a `marker` is found in the document, the Table of Contents is
60+
also available as an attribute (`toc`) of the Markdown class. This allows one to insert
6161
the Table of Contents elsewhere in their page template. For example:
6262

6363
>>> text = '''

‎docs/release-2.5.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
title: Release Notes for v2.5
2-
prev_title: Change Log
3-
prev_url: change_log.html
2+
prev_title: Release Notes for v2.6
3+
prev_url: release-2.6.html
44
next_title: Release Notes for v2.4
55
next_url: release-2.4.html
66

‎docs/release-2.6.txt‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
title: Release Notes for v2.6
2+
prev_title: Change Log
3+
prev_url: change_log.html
4+
next_title: Release Notes for v2.5
5+
next_url: release-2.5.html
6+
7+
Python-Markdown 2.6 Release Notes
8+
=================================
9+
10+
We are pleased to release Python-Markdown 2.6 which adds a few new features
11+
and fixes various bugs. See the list of changes below for details.
12+
13+
Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4.
14+
15+
Backwards-incompatible Changes
16+
------------------------------
17+
18+
* Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated
19+
in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and
20+
`html_replacement_text` keywords will be ignored in version 2.7. The so-called
21+
"safe mode" was never actually "safe" which has resulted in many people having a false
22+
sense of security when using it. As an alternative, the developers of Python-Markdown
23+
recommend that any untrusted content be passed through an HTML sanitizer (like [Bleach])
24+
after being converted to HTML by markdown.
25+
26+
If your code previously looked like this:
27+
28+
html = markdown.markdown(text, same_mode=True)
29+
30+
Then it is recommended that you change your code to read something like this:
31+
32+
import bleach
33+
html = bleach.clean(markdown.markdown(text))
34+
35+
If you are not interested in sanitizing untrusted text, but simply desire to escape
36+
raw HTML, then that can be accomplished through an extension which removes HTML parsing:
37+
38+
from markdown.extensions import Extension
39+
40+
class EscapeHtml(Extension):
41+
def extendMarkdown(self, md, md_globals):
42+
del md.preprocessors['html_block']
43+
del md.inlinePatterns['html']
44+
45+
html = markdown.markdown(text, extensions=[EscapeHtml()])
46+
47+
As the HTML would not be parsed with the above Extension, then the searializer will
48+
escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
49+
50+
[Bleach]: http://bleach.readthedocs.org/
51+
52+
* Positional arguments on the `markdown.Markdown()` are deprecated as are
53+
all except the `text` argument on the `markdown.markdown()` wrapper function.
54+
Using positional argument will raise a **`DeprecationWarning`** in 2.6 and an error
55+
in version 2.7. Only keyword arguments should be used. For example, if your code
56+
previosuly looked like this:
57+
58+
html = markdown.markdown(text, ['extra'])
59+
60+
Then it is recommended that you change it to read something like this:
61+
62+
html = markdown.markdown(text, extensions=['extra'])
63+
64+
!!! Note
65+
This change is being made as a result of deprecating `"safe_mode"` as the
66+
`safe_mode` argumnet was one of the positional arguments. When that argument
67+
is removed, the two arguments following it will no longer be at the correct
68+
position. It is recomended that you always use keywords when they are supported
69+
for this reason.
70+
71+
* In previous versions of Python-Markdown, the builtin extensions received
72+
special status and did not require the full path to be provided. Additionaly,
73+
third party extensions whose name started with "mdx_" received the same
74+
special treatment. This behavior is deprecated and will raise a
75+
**`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you
76+
always use the full path to your extensions. For example, if you previously
77+
did the following:
78+
79+
markdown.markdown(text, extensions=['extra'])
80+
81+
You should change your code to the following:
82+
83+
markdown.markdown(text, extensions=['markdown.extensions.extra'])
84+
85+
The same applies to the command line:
86+
87+
$ python -m markdown -x markdown.extensions.extra input.txt
88+
89+
See the [documentation](reference.html#extensions) for a full explaination
90+
of the current behavior.
91+
92+
* The previously documented method of appending the extension configs as
93+
a string to the extension name is deprecated and will raise a
94+
**`DeprecationWarning`** in version 2.6 and an error in 2.7.
95+
The [extension_configs](reference.html#extension_configs) keyword should
96+
be used instead. See the [documentation](reference.html#extension-configs)
97+
for a full explaination of the current behavior.
98+
99+
What's New in Python-Markdown 2.6
100+
---------------------------------
101+
102+
* The [Meta-Data] Extension now includes optional support for [YAML] style
103+
meta-data. By default, the YAML deliminators are recognized, however, the
104+
actual data is parsed as previously. This follows the syntax of
105+
[MultiMarkdown], which inspired this extension.
106+
107+
Alternatively, if the `yaml` option is set, then the data is parsed as YAML.
108+
109+
[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
110+
[Meta-Data]: extensions/meta_data.html
111+
[YAML]: http://yaml.org/
112+
113+
* The [TOC] Extension has been refactored. Significantly, the extension now
114+
assigns the Table of Contents to the `toc` attrbibute of the Markdown class
115+
regardless of whether a "marker" was found in the document. Third party
116+
frameworks no longer need to insert a "marker," run the document through
117+
Markdown, then extract the TOC from the document.
118+
119+
Additionaly, the TOC Extension is now a "registered extension." Therefore,
120+
when the `reset` method of the Markdown class is called, the `toc` attribute
121+
on the Markdown class is cleared (set to an empty string).
122+
123+
[TOC]: extensions/toc.html
124+
125+
* Test coverage has been improved including running [flake8]. While those changes
126+
will not directly effect end users, the code is being better tested which will
127+
benefit everyone.
128+
129+
[fake8]: http://flake8.readthedocs.org/en/latest/
130+
131+
* Various bug fixes have been made. See the
132+
[commit log](https://github.com/waylan/Python-Markdown/commits/master)
133+
for a complete history of the changes.

‎docs/siteindex.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ Table of Contents
6666
* [Syntax Test Config Settings](test_suite.html#syntax-test-config-settings)
6767
* [Unit Tests](test_suite.html#unit-tests)
6868
* [Change Log](change_log.html)
69+
* [Release Notes for v.2.6](release-2.6.html)
6970
* [Release Notes for v.2.5](release-2.5.html)
7071
* [Release Notes for v.2.4](release-2.4.html)
7172
* [Release Notes for v.2.3](release-2.3.html)

0 commit comments

Comments
 (0)