aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/release-2.6.txt342
1 files changed, 188 insertions, 154 deletions
diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt
index 0a95780..f222d6c 100644
--- a/docs/release-2.6.txt
+++ b/docs/release-2.6.txt
@@ -15,144 +15,168 @@ Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as w
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.
+### `safe_mode` Deprecated
- If your code previously looked like this:
+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.
- html = markdown.markdown(text, safe_mode=True)
+If your code previously looked like this:
- Then it is recommended that you change your code to read something like this:
+ html = markdown.markdown(text, safe_mode=True)
- import bleach
- html = bleach.clean(markdown.markdown(text))
+Then it is recommended that you change your code to read something like this:
- 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:
+ import bleach
+ html = bleach.clean(markdown.markdown(text))
- from markdown.extensions import Extension
+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:
- class EscapeHtml(Extension):
- def extendMarkdown(self, md, md_globals):
- del md.preprocessors['html_block']
- del md.inlinePatterns['html']
+ from markdown.extensions import Extension
- html = markdown.markdown(text, extensions=[EscapeHtml()])
+ class EscapeHtml(Extension):
+ def extendMarkdown(self, md, md_globals):
+ del md.preprocessors['html_block']
+ del md.inlinePatterns['html']
- As the HTML would not be parsed with the above Extension, then the serializer will
- escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
+ html = markdown.markdown(text, extensions=[EscapeHtml()])
+
+As the HTML would not be parsed with the above Extension, then the serializer 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()` 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
- previously looked like this:
+### Positional Arguments Deprecated
+
+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
+previously looked like this:
+
+ html = markdown.markdown(text, [SomeExtension()])
+
+Then it is recommended that you change it to read something like this:
+
+ html = markdown.markdown(text, extensions=[SomeExtension()])
+
+!!! 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 recommended that you always use keywords when they are supported
+ for this reason.
+
+### "Shortened" Extension Names Deprecated
+
+In previous versions of Python-Markdown, the built-in extensions received
+special status and did not require the full path to be provided. Additionally,
+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'])
- html = markdown.markdown(text, [SomeExtension()])
-
- Then it is recommended that you change it to read something like this:
+You should change your code to the following:
- html = markdown.markdown(text, extensions=[SomeExtension()])
+ markdown.markdown(text, extensions=['markdown.extensions.extra'])
- !!! 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 recommended that you always use keywords when they are supported
- for this reason.
+The same applies to the command line:
-* In previous versions of Python-Markdown, the built-in extensions received
- special status and did not require the full path to be provided. Additionally,
- 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:
+ $ python -m markdown -x markdown.extensions.extra input.txt
- markdown.markdown(text, extensions=['extra'])
+Similarly, if you have used a third party extension (eg: `mdx_math`), previously
+you might have called it like this:
- You should change your code to the following:
+ markdown.markdown(text, extensions=['math'])
- markdown.markdown(text, extensions=['markdown.extensions.extra'])
+As the `"mdx"` prefix will no longer be appended, you will need to change your code
+as follows (assuming the file `mdx_math.py` is installed at the root of your PYTHONPATH):
- The same applies to the command line:
+ markdown.markdown(text, extensions=['mdx_math'])
- $ python -m markdown -x markdown.extensions.extra input.txt
+Extension authors will want to update their documentation to reflect the new behavior.
- See the [documentation](reference.html#extensions) for a full explanation
- of the current behavior.
+See the [documentation](reference.html#extensions) for a full explanation
+of the current behavior.
-* The previously documented method of appending the extension configuration options 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 explanation of the current behavior.
+### Extension Configs as Part of Extension Name Deprecated
-* The [HeaderId][hid] Extension is pending deprecation and will raise a
- **`PendingDeprecationWarning`** in version 2.6. The extension will be
- deprecated in version 2.7 and raise an error in version 2.8. Use the
- [Table of Contents][TOC] Extension instead, which offers most of the
- features of the HeaderId Extension and more (support for meta data is missing).
-
- Extension authors who have been using the `slugify` and `unique` functions
- defined in the HeaderId Extension should note that those functions are now
- defined in the Table of Contents extension and should adjust their import
- statements accordingly (`from markdown.extensions.toc import slugify, unique`).
+The previously documented method of appending the extension configuration options 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 explanation of the current behavior.
+
+### HeaderId Extension Pending Deprecation
+
+The [HeaderId][hid] Extension is pending deprecation and will raise a
+**`PendingDeprecationWarning`** in version 2.6. The extension will be
+deprecated in version 2.7 and raise an error in version 2.8. Use the
+[Table of Contents][TOC] Extension instead, which offers most of the
+features of the HeaderId Extension and more (support for meta data is missing).
+
+Extension authors who have been using the `slugify` and `unique` functions
+defined in the HeaderId Extension should note that those functions are now
+defined in the Table of Contents extension and should adjust their import
+statements accordingly (`from markdown.extensions.toc import slugify, unique`).
[hid]: extensions/header_id.html
-* Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class
- (and its subclasses) are deprecated. Each individual configuration option should be passed
- to the class as a keyword/value pair. For example. one might have previously initiated
- an extension subclass like this:
-
- ext = SomeExtension(configs={'somekey': 'somevalue'})
-
- That code should be updated to pass in the options directly:
-
- ext = SomeExtension(somekey='somevalue')
-
- Extension authors will want to note that this affects the `makeExtension` function as well.
- Previously it was common for the function to be defined as follows:
-
- def makeExtension(configs=None):
- return SomeExtension(configs=configs)
-
- Extension authors will want to update their code to the following instead:
-
- def makeExtension(**kwargs):
- return SomeExtension(**kwargs)
-
- Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next
- release. See the [Extension API][mext] documentation for more information.
-
- In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method
- and implements its own configuration handling, then the above may not apply. However, it is
- recommended that the subclass still calls the parent `__init__` method to handle configuration
- options like so:
-
- class SomeExtension(markdown.extension.Extension):
- def __init__(**kwargs):
- # Do pre-config stuff here
- # Set config defaults
- self.config = {
- 'option1' : ['value1', 'description1'],
- 'option2' : ['value2', 'description2']
- }
- # Set user defined configs
- super(MyExtension, self).__init__(**kwargs)
- # Do post-config stuff here
-
- Note the call to `super` to get the benefits of configuration handling from the parent class.
- See the [documentation][config] for more information.
+### `configs` Keyword Deprecated
+
+Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class
+(and its subclasses) are deprecated. Each individual configuration option should be passed
+to the class as a keyword/value pair. For example. one might have previously initiated
+an extension subclass like this:
+
+ ext = SomeExtension(configs={'somekey': 'somevalue'})
+
+That code should be updated to pass in the options directly:
+
+ ext = SomeExtension(somekey='somevalue')
+
+Extension authors will want to note that this affects the `makeExtension` function as well.
+Previously it was common for the function to be defined as follows:
+
+ def makeExtension(configs=None):
+ return SomeExtension(configs=configs)
+
+Extension authors will want to update their code to the following instead:
+
+ def makeExtension(**kwargs):
+ return SomeExtension(**kwargs)
+
+Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next
+release. See the [Extension API][mext] documentation for more information.
+
+In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method
+and implements its own configuration handling, then the above may not apply. However, it is
+recommended that the subclass still calls the parent `__init__` method to handle configuration
+options like so:
+
+ class SomeExtension(markdown.extension.Extension):
+ def __init__(**kwargs):
+ # Do pre-config stuff here
+ # Set config defaults
+ self.config = {
+ 'option1' : ['value1', 'description1'],
+ 'option2' : ['value2', 'description2']
+ }
+ # Set user defined configs
+ super(MyExtension, self).__init__(**kwargs)
+ # Do post-config stuff here
+
+Note the call to `super` to get the benefits of configuration handling from the parent class.
+See the [documentation][config] for more information.
[config]: extensions/api.html#configsettings
[mext]: extensions/api.html#makeextension
@@ -160,66 +184,76 @@ Backwards-incompatible Changes
What's New in Python-Markdown 2.6
---------------------------------
-* Official support for [PyPy] has been added. While Python-Markdown has most likely
+### Official Support for PyPy
+
+Official support for [PyPy] has been added. While Python-Markdown has most likely
worked on PyPy for some time, it is now officially supported and tested on PyPy.
[PyPy]: http://pypy.org/
-* 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.
+### YAML Style Meta-Data
+
+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.
+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 [Table of Contents][TOC] Extension has been refactored and some new features
- have been added. See the documentation for a full explanation of each feature
- listed below:
-
- * 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 Table of Contents from the document.
-
- * The Table of Contents 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).
-
- * When the `marker` configuration 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 Table of Contents Extension is being used only to assign ids to headers.
-
- * A `separator` configuration option has been added allowing users to override the
- separator character used by the slugify function.
-
- * A `baselevel` configuration option has been added allowing users to set the base level
- of headers in their documents (h1-h6). This allows the header levels to be
- automatically adjusted to fit within the hierarchy of an HTML template.
+### TOC Extension Refactored
+
+The [Table of Contents][TOC] Extension has been refactored and some new features
+have been added. See the documentation for a full explanation of each feature
+listed below:
+
+* 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 Table of Contents from the document.
+
+* The Table of Contents 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).
+
+* When the `marker` configuration 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 Table of Contents Extension is being used only to assign ids to headers.
+
+* A `separator` configuration option has been added allowing users to override the
+ separator character used by the slugify function.
+
+* A `baselevel` configuration option has been added allowing users to set the base level
+ of headers in their documents (h1-h6). This allows the header levels to be
+ automatically adjusted to fit within the hierarchy of an HTML template.
[TOC]: extensions/toc.html
-* The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`.
- The option is `True` by default, however, it allows one to turn off Pygments code
- highlighting (set to `False`) while preserving the language detection features of
- the extension. Note that Pygments language guessing is not used as that would 'use
- Pygments'. If a language is defined for a code block, it will be assigned to the
- `<code>` tag as a class in the manner suggested by the [HTML5 spec][spec]
- (alternate output will not be entertained) and could potentially be used by a JavaScript
- library in the browser to highlight the code block.
+### Pygments can now be disabled
+
+The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`.
+The option is `True` by default, however, it allows one to turn off Pygments code
+highlighting (set to `False`) while preserving the language detection features of
+the extension. Note that Pygments language guessing is not used as that would 'use
+Pygments'. If a language is defined for a code block, it will be assigned to the
+`<code>` tag as a class in the manner suggested by the [HTML5 spec][spec]
+(alternate output will not be entertained) and could potentially be used by a JavaScript
+library in the browser to highlight the code block.
[ch]: extensions/code_hilite.html
[spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
-* 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.
+### Miscellaneous
+
+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.
[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)
- for a complete history of the changes.
+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.