From b62ddeda02fadcd09def9354eb2ef46a7562a106 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 6 Dec 2017 23:18:29 -0500 Subject: Switch docs to MKDocs (#602) Fixes #601. Merged in 6f87b32 from the md3 branch and did a lot of cleanup. Changes include: * Removed old docs build tool, templates, etc. * Added MkDocs config file, etc. * filename.txt => filename.md * pythonhost.org/Markdown => Python-Markdown.github.io * Markdown lint and other cleanup. * Automate pages deployment in makefile with `mkdocs gh-deploy` Assumes a git remote is set up named "pages". Do git remote add pages https://github.com/Python-Markdown/Python-Markdown.github.io.git ... before running `make deploy` the first time. --- docs/change_log/release-2.6.md | 306 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 306 insertions(+) create mode 100644 docs/change_log/release-2.6.md (limited to 'docs/change_log/release-2.6.md') diff --git a/docs/change_log/release-2.6.md b/docs/change_log/release-2.6.md new file mode 100644 index 0000000..1495072 --- /dev/null +++ b/docs/change_log/release-2.6.md @@ -0,0 +1,306 @@ +title: Release Notes for v2.6 + +# Python-Markdown 2.6 Release Notes + +We are pleased to release Python-Markdown 2.6 which adds a few new features +and fixes various bugs. See the list of changes below for details. + +Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as +well as PyPy. + +## Backwards-incompatible Changes + +### `safe_mode` Deprecated + +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 the next +release. 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. In fact, [Bleach Whitelist] provides a curated +list of tags, attributes, and styles suitable for filtering user-provided HTML +using bleach. + +If your code previously looked like this: + +```python +html = markdown.markdown(text, safe_mode=True) +``` + +Then it is recommended that you change your code to read something like this: + +```python +import bleach +from bleach_whitelist import markdown_tags, markdown_attrs +html = bleach.clean(markdown.markdown(text), markdown_tags, markdown_attrs) +``` + +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: + +```python +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 serializer +will escape the raw HTML, which is exactly what happens now when +`safe_mode="escape"`. + +[Bleach]: https://bleach.readthedocs.io/ +[Bleach Whitelist]: https://github.com/yourcelf/bleach-whitelist + +### 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 the next release. Only keyword arguments should be used. For example, +if your code previously looked like this: + +```python +html = markdown.markdown(text, [SomeExtension()]) +``` + +Then it is recommended that you change it to read something like this: + +```python +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 the next release. Ensure +that you always use the full path to your extensions. For example, if you +previously did the following: + +```python +markdown.markdown(text, extensions=['extra']) +``` + +You should change your code to the following: + +```python +markdown.markdown(text, extensions=['markdown.extensions.extra']) +``` + +The same applies to the command line: + +```python +python -m markdown -x markdown.extensions.extra input.txt +``` + +Similarly, if you have used a third party extension (for example `mdx_math`), +previously you might have called it like this: + +```python +markdown.markdown(text, extensions=['math']) +``` + +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): + +```python +markdown.markdown(text, extensions=['mdx_math']) +``` + +Extension authors will want to update their documentation to reflect the new +behavior. + +See the [documentation](../reference.md#extensions) for a full explanation +of the current behavior. + +### Extension Configuration as Part of Extension Name Deprecated + +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.md#extension_configs) keyword should be used +instead. See the [documentation](../reference.md#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 the next release and raise an error in the release after that. 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.md + +### The `configs` Keyword is 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: + +```python +ext = SomeExtension(configs={'somekey': 'somevalue'}) +``` + +That code should be updated to pass in the options directly: + +```python +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: + +```python +def makeExtension(configs=None): + return SomeExtension(configs=configs) +``` + +Extension authors will want to update their code to the following instead: + +```python +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: + +```python +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.md#configsettings +[mext]: ../extensions/api.md#makeextension + +## What's New in Python-Markdown 2.6 + +### 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/ + +### 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. As the `yaml` option was buggy, it was removed in 2.6.1. It is +suggested that a preprocessor (like [docdata]) or a third party extension be +used if you want true YAML support. See [Issue #390][#390] for a full +explanation. + +[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata +[Meta-Data]: ../extensions/meta_data.md +[YAML]: http://yaml.org/ +[#390]: https://github.com/Python-Markdown/markdown/issues/390 +[docdata]: https://github.com/waylan/docdata + +### Table of Contents 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.md + +### 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 `` 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.md +[spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element + +### 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]: https://flake8.readthedocs.io/en/latest/ + +Various bug fixes have been made. See the +[commit log](https://github.com/Python-Markdown/markdown/commits/master) +for a complete history of the changes. -- cgit v1.2.3