diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.txt | 7 | ||||
| -rw-r--r-- | docs/reference.txt | 33 | ||||
| -rw-r--r-- | docs/release-2.5.txt | 57 |
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. |