aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/index.txt7
-rw-r--r--docs/reference.txt33
-rw-r--r--docs/release-2.5.txt57
3 files changed, 72 insertions, 25 deletions
diff --git a/docs/index.txt b/docs/index.txt
index edf1cbd..bfe1818 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -54,13 +54,6 @@ features:
Python-Markdown can output documents in HTML4, XHTML and HTML5. See the
[Library Reference](reference.html#output_format) for details.
-* __"Safe Mode"__
-
- When using Python-Markdown to parse input from untrusted users on the web,
- the handling of raw HTML can be controlled in various ways to prevent
- harmful code from being injected into your site. See the
- [Library Reference](reference.html#safe_mode) for details.
-
* __Command Line Interface__
In addition to being a Python Library, a
diff --git a/docs/reference.txt b/docs/reference.txt
index e1797ad..2e1985d 100644
--- a/docs/reference.txt
+++ b/docs/reference.txt
@@ -165,10 +165,20 @@ The following options are available on the `markdown.markdown` function:
* __`safe_mode`__{: #safe_mode }: Disallow raw html.
- If you are using Markdown on a web system which will transform text
- provided by untrusted users, you may want to use the "safe_mode"
- option which ensures that the user's HTML tags are either replaced,
- removed or escaped. (They can still create links using Markdown syntax.)
+ !!! warning
+ "`safe_mode`" is pending deprecation and should not be used.
+
+ HTML sanitizers (like [Bleach]) provide a better solution for
+ dealing with markdown text submitted by untrusted users.
+
+ import markdown
+ import bleach
+ html = bleach.clean(markdown.markdown(untrusted_text))
+
+ See the [release notes] for more info.
+
+[Bleach]: https://github.com/jsocol/bleach
+[release notes]: release-2.5.html
The following values are accepted:
@@ -200,21 +210,14 @@ The following options are available on the `markdown.markdown` function:
"safe_mode" also alters the default value for the
[`enable_attributes`](#enable_attributes) option.
- !!! seealso "See Also"
- HTML sanitizers (like [Bleach]) may provide a better solution for
- dealing with markdown text submitted by untrusted users. That way,
- both the HTML generated by Markdown and user submited raw HTML are
- fully sanitized.
-
- import markdown
- import bleach
- html = bleach.clean(markdown.markdown(evil_text))
-
-[Bleach]: https://github.com/jsocol/bleach
* __`html_replacement_text`__{: #html_replacement_text }: Text used when
safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`.
+ !!! warning
+ "`html_replacement_text`" is pending deprecation and should not be used.
+ See the [release notes] for more info.
+
* __`tab_length`__{: #tab_length }: Length of tabs in the source. Default: 4
* __`enable_attributes`__{: #enable_attributes}: Enable the conversion of
diff --git a/docs/release-2.5.txt b/docs/release-2.5.txt
index 044fcb2..207d876 100644
--- a/docs/release-2.5.txt
+++ b/docs/release-2.5.txt
@@ -23,7 +23,7 @@ Backwards-incompatible Changes
[importlib]: https://pypi.python.org/pypi/importlib
-* The `force_linenos` config key on the [CodeHilite Extension] has been deprecated
+* The `force_linenos` config key on the [CodeHilite Extension] has been **deprecated**
and will raise a `KeyError` if provided. In the previous release (2.4), it was
issuing a `DeprecationWarning`. The [`linenums`][linenums] keyword should be used
instead, which provides more control of the output.
@@ -31,11 +31,62 @@ Backwards-incompatible Changes
[CodeHilite Extension]: extensions/code_hilite.html
[linenums]: extensions/code_hilite.html#usage
+* Both `safe_mode` and the associated `html_replacement_text` keywords will be deprecated
+ in version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. 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 pending deprecation as are
+ all except the `text` argument on the `markdown.markdown()` wrapper function.
+ 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 will be deprecated in version 2.6 and will
- raise a `PendingDeprecationWarning` in 2.5. Ensure that you always use the full
+ raise a **`PendingDeprecationWarning`** in 2.5. Ensure that you always use the full
path to your extensions. For example, if you previously did the following:
markdown.markdown(text, extensions=['extra'])
@@ -53,7 +104,7 @@ Backwards-incompatible Changes
* The previously documented method of appending the extension configs as
a string to the extension name will be deprecated in Python-Markdown
- version 2.6 and will raise a `PendingDeprecationWarning` in 2.5. The
+ version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. 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.