diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/extensions/toc.txt | 12 | ||||
| -rw-r--r-- | docs/release-2.6.txt | 94 |
2 files changed, 51 insertions, 55 deletions
diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt index c6a99bf..0705564 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.txt @@ -90,13 +90,11 @@ The following options are provided to configure the output: Set to `True` or a string to generate permanent links at the end of each header. Useful with Sphinx stylesheets. - When set to `True` the paragraph symbol (¶ -- `¶`) is used as the link + When set to `True` the paragraph symbol (¶ or "`¶`") is used as the link text. When set to a string, the provided string is used as the link text. * **`baselevel`**: - Base level for headers. - - Default: `1` + Base level for headers. Defaults to `1`. The `baselevel` setting allows the header levels to be automatically adjusted to fit within the hierarchy of your html templates. For example, suppose the @@ -106,7 +104,7 @@ The following options are provided to configure the output: >>> text = ''' ... #Some Header ... ## Next Level''' - >>> from markdown.extensions.toc import TocExtension + >>> from markdown.extensions.toc import TocExtension >>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)]) >>> print html <h3 id="some_header">Some Header</h3> @@ -126,6 +124,4 @@ The following options are provided to configure the output: The callable must return a string appropriate for use in HTML `id` attributes. * **`separator`**: - Word separator. Character which replaces whitespace in id. - - Default: `-`
\ No newline at end of file + Word separator. Character which replaces whitespace in id. Defaults to "`-`".
\ No newline at end of file diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt index dee771b..2aaf20b 100644 --- a/docs/release-2.6.txt +++ b/docs/release-2.6.txt @@ -15,58 +15,58 @@ 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. +* 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, safe_mode=True) + html = markdown.markdown(text, safe_mode=True) - Then it is recommended that you change your code to read something like this: + Then it is recommended that you change your code to read something like this: - import bleach + 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: + 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 + from markdown.extensions import Extension - class EscapeHtml(Extension): - def extendMarkdown(self, md, md_globals): - del md.preprocessors['html_block'] - del md.inlinePatterns['html'] + class EscapeHtml(Extension): + def extendMarkdown(self, md, md_globals): + del md.preprocessors['html_block'] + del md.inlinePatterns['html'] - html = markdown.markdown(text, extensions=[EscapeHtml()]) + 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"`. + 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: +* Positional arguments on the `markdown.Markdown()` class are deprecated as are + all except the `text` argument on the `markdown.markdown()` wrapper function. + Using positional arguments 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']) + html = markdown.markdown(text, [SomeExtension()]) - Then it is recommended that you change it to read something like this: + Then it is recommended that you change it to read something like this: - html = markdown.markdown(text, extensions=['extra']) + html = markdown.markdown(text, extensions=[SomeExtension()]) - !!! 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. + !!! Note + This change is being made as a result of deprecating `"safe_mode"` as the + `safe_mode` argument 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, @@ -80,7 +80,7 @@ Backwards-incompatible Changes You should change your code to the following: - markdown.markdown(text, extensions=['markdown.extensions.extra']) + markdown.markdown(text, extensions=['markdown.extensions.extra']) The same applies to the command line: @@ -89,12 +89,12 @@ Backwards-incompatible Changes 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. +* 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. * The [HeaderId][hid] Extension is pending deprecation and will raise a **`PendingDeprecationWarning`** in version 2.6. The extension will be @@ -107,7 +107,7 @@ Backwards-incompatible Changes defined in the Table of Contents extension and should adjust their import statements accordingly (`from markdown.extensions.toc import slugify, unique`). -[hid]: extensions/headerid.html +[hid]: extensions/header_id.html What's New in Python-Markdown 2.6 --------------------------------- @@ -129,16 +129,16 @@ What's New in Python-Markdown 2.6 * The extension now assigns the Table of Contents to the `toc` attribute 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. + Third party frameworks no longer need to insert a "marker," run the document + through Markdown, then extract the TOC from the document. * 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). + class is cleared (set to an empty string). * When the `marker` config option is set to an empty string, the parser completely skips the process of searching the document for markers. This should save parsing - time when the TOC Extension is being used only to assign ids to headers. + time when the TOC Extension is being used only to assign ids to headers. * A `separator` config option has been added allowing users to override the separator character used by the slugify function. @@ -153,7 +153,7 @@ What's New in Python-Markdown 2.6 will not directly effect end users, the code is being better tested which will benefit everyone. -[fake8]: http://flake8.readthedocs.org/en/latest/ +[flake8]: http://flake8.readthedocs.org/en/latest/ * Various bug fixes have been made. See the [commit log](https://github.com/waylan/Python-Markdown/commits/master) |