From 90acf0eb9fce942482961af9a1da44c4d2e1a469 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 6 Dec 2017 18:34:42 -0500 Subject: [PATCH] Restore some md3 branch deletions which are not (yet) relevent. --- docs/change_log/release-2.1.md | 90 +++++++++++++++---------------- docs/change_log/release-2.2.md | 32 ++++++------ docs/change_log/release-2.3.md | 44 ++++++++-------- docs/change_log/release-2.4.md | 28 ++++++---- docs/change_log/release-2.5.md | 96 ++++++++++++++++++---------------- docs/change_log/release-2.6.md | 40 ++++++++------ docs/extensions/index.md | 45 ++++++++-------- docs/index.md | 68 ++++++++++++------------ 8 files changed, 233 insertions(+), 210 deletions(-) diff --git a/docs/change_log/release-2.1.md b/docs/change_log/release-2.1.md index ad75ac986..52697b55d 100644 --- a/docs/change_log/release-2.1.md +++ b/docs/change_log/release-2.1.md @@ -3,14 +3,14 @@ title: Release Notes for v2.1 Python-Markdown 2.1 Release Notes ================================= -We are pleased to release Python-Markdown 2.1 which makes many -improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. -While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline -with other implementations, some internal improvements were made to the parser, +We are pleased to release Python-Markdown 2.1 which makes many +improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. +While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline +with other implementations, some internal improvements were made to the parser, a few new built-in extensions were added, and HTML5 support was added. -Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out -of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no +Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out +of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no extra work by the end user. Backwards-incompatible Changes @@ -19,34 +19,34 @@ Backwards-incompatible Changes While Python-Markdown has received only minor internal changes since the last release, there are a few backward-incompatible changes to note: -* Support had been dropped for Python 2.3. No guarantees are made that the -library will work in any version of Python lower than 2.4. Additionally, while -the library had been tested with Python 2.4, consider Python 2.4 support to be +* Support had been dropped for Python 2.3. No guarantees are made that the +library will work in any version of Python lower than 2.4. Additionally, while +the library had been tested with Python 2.4, consider Python 2.4 support to be depreciated. It is not likely that any future versions will continue to support -any version of Python less than 2.5. Note that Python 3.0 is not supported due -to a bug in its 2to3 tool. If you must use Python-Markdown with Python 3.0, it +any version of Python less than 2.5. Note that Python 3.0 is not supported due +to a bug in its 2to3 tool. If you must use Python-Markdown with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to do a conversion. * Python-Markdown previously accepted positional arguments on its class and wrapper methods. It now expects keyword arguments. Currently, the positional -arguments should continue to work, but the solution feels hacky and may be -removed in a future version. All users are encouraged to use keyword arguments +arguments should continue to work, but the solution feels hacky and may be +removed in a future version. All users are encouraged to use keyword arguments as documented in the [Library Reference](../reference.md). * Past versions of Python-Markdown provided module level Global variables which controlled the behavior of a few different aspects of the parser. Those global -variables have been replaced with attributes on the Markdown class. -Additionally, those attributes are settable as keyword arguments when -initializing a class instance. Therefore, if you were editing the global -variables (either by editing the source or by overriding them in your code), -you should now set them on the class. See the +variables have been replaced with attributes on the Markdown class. +Additionally, those attributes are settable as keyword arguments when +initializing a class instance. Therefore, if you were editing the global +variables (either by editing the source or by overriding them in your code), +you should now set them on the class. See the [Library Reference](../reference.md) for the options available. -* If you have been using the HeaderId extension -to define custom ids on headers, you will want to switch to using the new -Attribute List extension. The HeaderId extension -now only auto-generates ids on headers which have not already had ids defined. -Note that the Extra extension has been switched to use +* If you have been using the [HeaderId](../extensions.md) extension +to define custom ids on headers, you will want to switch to using the new +[Attribute List](../extensions/attr_list.md) extension. The HeaderId extension +now only auto-generates ids on headers which have not already had ids defined. +Note that the [Extra](../extensions/extra.md) extension has been switched to use Attribute Lists instead of HeaderId as it did previously. * Some code was moved into the `markdown.util` namespace which was previously @@ -63,25 +63,25 @@ may want to remove them yourself as they are unlikely to work properly. What's New in Python-Markdown 2.1 --------------------------------- -Three new extensions were added. Attribute Lists, -which was inspired by Maruku's feature of the same name, -Newline to Break, which was inspired by GitHub -Flavored Markdown, and Smart Strong, which +Three new extensions were added. [Attribute Lists](../extensions/attr_list.md), +which was inspired by Maruku's feature of the same name, +[Newline to Break](../extensions/nl2br.md), which was inspired by GitHub +Flavored Markdown, and [Smart Strong](../extensions/smart_strong.md), which fills a hole in the Extra extension. -HTML5 is now supported. All this really means is that new block level elements +HTML5 is now supported. All this really means is that new block level elements introduced in the HTML5 spec are now properly recognized as raw HTML. As valid HTML5 can consist of either HTML4 or XHTML1, there is no need to add a -new HTML5 serializers. That said, `html5` and `xhtml5` have been added as +new HTML5 serializers. That said, `html5` and `xhtml5` have been added as aliases of the `html4` and `xhtml1` serializers respectively. -An XHTML serializer has been added. Previously, ElementTree's XML serializer +An XHTML serializer has been added. Previously, ElementTree's XML serializer was being used for XHTML output. With the new serializer we are able to avoid -more invalid output like empty elements (i.e., `

`) which can choke +more invalid output like empty elements (i.e., `

`) which can choke browsers. -Improved support for Python 3.x. Now when running `setupy.py install` in -Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 +Improved support for Python 3.x. Now when running `setupy.py install` in +Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0 is not supported due to a bug in its 2to3 tool. If you must use Python-Markdown with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to do a conversion. @@ -89,30 +89,30 @@ do a conversion. Methods on instances of the Markdown class that do not return results can now be changed allowing one to do `md.reset().convert(moretext)`. -The Markdown class was refactored so that a subclass could define it's own +The Markdown class was refactored so that a subclass could define it's own `build_parser` method which would build a completely different parser. In -other words, one could use the basic machinery in the markdown library to +other words, one could use the basic machinery in the markdown library to build a parser of a different markup language without the overhead of building the markdown parser and throwing it away. -Import statements within markdown have been improved so that third party +Import statements within markdown have been improved so that third party libraries can embed the markdown library if they desire (licensing permitting). -Added support for Python's `-m` command line option. You can run the markdown -package as a command line script. Do `python -m markdown [options] [args]`. -Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 +Added support for Python's `-m` command line option. You can run the markdown +package as a command line script. Do `python -m markdown [options] [args]`. +Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 require you to call the module directly (`markdown.__main__`) rather than the package (`markdown`). This does not work in Python 2.4. -The command line script has been renamed to `markdown_py` which avoids all the -various problems we had with previous names. Also improved the command line +The command line script has been renamed to `markdown_py` which avoids all the +various problems we had with previous names. Also improved the command line script to accept input on `stdin`. -The testing framework has been completely rebuilt using the Nose testing +The testing framework has been completely rebuilt using the Nose testing framework. This provides a number of benefits including the ability to better -test the built-in extensions and other options available to change the parsing +test the built-in extensions and other options available to change the parsing behavior. See the [Test Suite](../test_suite.md) documentation for details. -Various bug fixes have been made, which are too numerous to list here. See the -[commit log](https://github.com/Python-Markdown/markdown/commits/master) for a +Various bug fixes have been made, which are too numerous to list here. See the +[commit log](https://github.com/Python-Markdown/markdown/commits/master) for a complete history of the changes. diff --git a/docs/change_log/release-2.2.md b/docs/change_log/release-2.2.md index 5533eadf2..1f2a68bc0 100644 --- a/docs/change_log/release-2.2.md +++ b/docs/change_log/release-2.2.md @@ -3,12 +3,12 @@ title: Release Notes for v2.2 Python-Markdown 2.2 Release Notes ================================= -We are pleased to release Python-Markdown 2.2 which makes improvements on 2.1. -While 2.2 is primarily a bug fix release, some internal improvements were made +We are pleased to release Python-Markdown 2.2 which makes improvements on 2.1. +While 2.2 is primarily a bug fix release, some internal improvements were made to the parser, and a few security issues were resolved. -Python-Markdown supports Python versions 2.5, 2.6, 2.7, 3.1, and 3.2 out -of the box. +Python-Markdown supports Python versions 2.5, 2.6, 2.7, 3.1, and 3.2 out +of the box. Backwards-incompatible Changes ------------------------------ @@ -16,13 +16,13 @@ Backwards-incompatible Changes While Python-Markdown has received only minor internal changes since the last release, there are a few backward-incompatible changes to note: -* Support had been dropped for Python 2.4. No guarantees are made that the -library will work in any version of Python lower than 2.5. Additionally, while -the library had been tested with Python 2.5, consider Python 2.5 support to be +* Support had been dropped for Python 2.4. No guarantees are made that the +library will work in any version of Python lower than 2.5. Additionally, while +the library had been tested with Python 2.5, consider Python 2.5 support to be depreciated. It is not likely that any future versions will continue to support any version of Python less than 2.6. -* For many years Python-Markdown has identified `` and `` tags in +* For many years Python-Markdown has identified `` and `` tags in raw HTML input as block level tags. As they are actually inline level tags, this behavior has been changed. This may result in slightly different output. While in most cases, the new output is more correct, there may be a few edge @@ -30,21 +30,21 @@ cases where a document author has relied on the previous incorrect behavior. It is likely that a few adjustments may need to be made to those documents. * The behavior of the `enable_attributes` keyword has been slightly altered. -If authors have been using attributes in documents with `safe_mode` on, those +If authors have been using attributes in documents with `safe_mode` on, those attributes will no longer be parsed unless `enable_attributes` is explicitly set to `True`. This change was made to prevent untrusted authors from injecting -potentially harmful JavaScript in documents. This change had no effect when +potentially harmful JavaScript in documents. This change had no effect when not in `safe_mode`. What's New in Python-Markdown 2.2 --------------------------------- -The docs were refactored and can now be found at +The docs were refactored and can now be found at . The docs are now maintained in the Repository and are generated by the `setup.py build_docs` command. -The Sane_Lists -extension was added. The Sane Lists Extension alters the behavior of the +The [Sane_Lists](../extensions/sane_lists.md) +extension was added. The Sane Lists Extension alters the behavior of the Markdown List syntax to be less surprising by not allowing the mixing of list types. In other words, an ordered list will not continue when an unordered list item is encountered and vice versa. @@ -56,9 +56,9 @@ As long as the provided module contains a compatible extension, the extension will be loaded. The BlockParser API was slightly altered to allow `blockprocessor.run` to return -`True` or `False` which provides more control to the block processor loop from +`True` or `False` which provides more control to the block processor loop from within any Blockprocessor instance. -Various bug fixes have been made. See the -[commit log](https://github.com/Python-Markdown/markdown/commits/master) +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. diff --git a/docs/change_log/release-2.3.md b/docs/change_log/release-2.3.md index 449db6aed..fb3d96224 100644 --- a/docs/change_log/release-2.3.md +++ b/docs/change_log/release-2.3.md @@ -4,8 +4,8 @@ Python-Markdown 2.3 Release Notes ================================= We are pleased to release Python-Markdown 2.3 which adds one new extension, -removes a few old (obsolete) extensions, and now runs on both Python 2 and -Python 3 without running the 2to3 conversion tool. See the list of changes +removes a few old (obsolete) extensions, and now runs on both Python 2 and +Python 3 without running the 2to3 conversion tool. See the list of changes below for details. Python-Markdown supports Python versions 2.6, 2.7, 3.1, 3.2, and 3.3. @@ -15,17 +15,17 @@ Backwards-incompatible Changes * Support has been dropped for Python 2.5. No guarantees are made that the library will work in any version of Python lower than 2.6. As all supported -Python versions include the ElementTree library, Python-Markdown will no +Python versions include the ElementTree library, Python-Markdown will no longer try to import a third-party installation of ElementTree. * All classes are now "new-style" classes. In other words, all classes -subclass from 'object'. While this is not likely to affect most users, +subclass from 'object'. While this is not likely to affect most users, extension authors may need to make a few minor adjustments to their code. * "safe_mode" has been further restricted. Markdown formatted links must be of a known white-listed scheme when in "safe_mode" or the URL is discarded. The white-listed schemes are: 'HTTP', 'HTTPS', 'FTP', 'FTPS', 'MAILTO', and -'news'. Schemeless URLs are also permitted, but are checked in other ways - +'news'. Schemeless URLs are also permitted, but are checked in other ways - as they have been for some time. * The ids assigned to footnotes now contain a dash (`-`) rather than a colon @@ -36,24 +36,25 @@ you are outputting XHTML (the default) or HTML4. * The `force_linenos` configuration setting of the CodeHilite extension has been marked as **Pending Deprecation** and a new setting `linenums` has been added to -replace it. See documentation for the CodeHilite Extension for an explanation -of the new `linenums` setting. The new setting will honor the old -`force_linenos` if it is set, but it will raise a `PendingDeprecationWarning` +replace it. See documentation for the [CodeHilite Extension] for an explanation +of the new `linenums` setting. The new setting will honor the old +`force_linenos` if it is set, but it will raise a `PendingDeprecationWarning` and will likely be removed in a future version of Python-Markdown. +[CodeHilite Extension]: ../extensions/codehilite.md * The "RSS" extension has been removed and no longer ships with Python-Markdown. -If you would like to continue using the extension (not recommended), it is +If you would like to continue using the extension (not recommended), it is archived on [GitHub](https://gist.github.com/waylan/4773365). * The "HTML Tidy" Extension has been removed and no longer ships with Python-Markdown. -If you would like to continue using the extension (not recommended), it is -archived on [GitHub](https://gist.github.com/waylan/5152650). Note that the -underlying library, uTidylib, is not Python 3 compatible. Instead, it is -recommended that the newer [PyTidyLib] (version 0.2.2+ for Python 3 -comparability - install from GitHub not PyPI) be used. As the API for that -library is rather simple, it is recommended that the output of Markdown be -wrapped in a call to PyTidyLib rather than using an extension (for example: +If you would like to continue using the extension (not recommended), it is +archived on [GitHub](https://gist.github.com/waylan/5152650). Note that the +underlying library, uTidylib, is not Python 3 compatible. Instead, it is +recommended that the newer [PyTidyLib] (version 0.2.2+ for Python 3 +comparability - install from GitHub not PyPI) be used. As the API for that +library is rather simple, it is recommended that the output of Markdown be +wrapped in a call to PyTidyLib rather than using an extension (for example: `tidylib.tidy_fragment(markdown.markdown(source), options={...})`). [PyTidyLib]: http://countergram.com/open-source/pytidylib @@ -65,16 +66,17 @@ What's New in Python-Markdown 2.3 any need for running the 2to3 conversion tool. This not only simplifies testing, but by using Unicode_literals, results in more consistent behavior across Python versions. Additionally, the relative imports (made possible in Python 2 -via absolute_import) allows the entire library to more easily be embedded in a -sub-directory of another project. The various files within the library will +via absolute_import) allows the entire library to more easily be embedded in a +sub-directory of another project. The various files within the library will still import each other properly even though 'markdown' may not be in Python's root namespace. -* The Admonition Extension has been added, which implements [rST-style][rST] -admonitions in the Markdown syntax. However, be warned that this extension -is experimental and the syntax and behavior is still subject to change. Please +* The [Admonition Extension] has been added, which implements [rST-style][rST] +admonitions in the Markdown syntax. However, be warned that this extension +is experimental and the syntax and behavior is still subject to change. Please try it out and report bugs and/or improvements. +[Admonition Extension]: ../extensions/admonition.md [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions * Various bug fixes have been made. See the diff --git a/docs/change_log/release-2.4.md b/docs/change_log/release-2.4.md index c6a3034e4..5b279839a 100644 --- a/docs/change_log/release-2.4.md +++ b/docs/change_log/release-2.4.md @@ -13,12 +13,14 @@ Backwards-incompatible Changes * The `force_linenos` configuration setting of the CodeHilite extension has been marked as **Deprecated**. It had previously been marked as "Pending Deprecation" -in version 2.3 when a new setting `linenums` was added to replace it. See -documentation for the CodeHilite Extension for an explanation of the new -`linenums` setting. The new setting will honor the old `force_linenos` if it -is set, but `force_linenos` will raise a `DeprecationWarning` and will likely +in version 2.3 when a new setting `linenums` was added to replace it. See +documentation for the [CodeHilite Extension] for an explanation of the new +`linenums` setting. The new setting will honor the old `force_linenos` if it +is set, but `force_linenos` will raise a `DeprecationWarning` and will likely be removed in a future version of Python-Markdown. +[CodeHilite Extension]: ../extensions/codehilite.md + * URLs are no longer percent-encoded. This improves compatibility with the original (written in Perl) Markdown implementation. Please percent-encode your URLs manually when needed. @@ -26,31 +28,34 @@ your URLs manually when needed. What's New in Python-Markdown 2.4 --------------------------------- -* Thanks to the hard work of [Dmitry Shachnev] the Smarty Extension has been -added, which implements [SmartyPants] using Python-Markdown's Extension API. +* Thanks to the hard work of [Dmitry Shachnev] the [Smarty Extension] has been +added, which implements [SmartyPants] using Python-Markdown's Extension API. This offers a few benefits over a third party script. The HTML does not need to be "tokenized" twice, no hacks are required to combine SmartyPants and -code highlighting, and we get markdown's escaping feature for free. Please try +code highlighting, and we get markdown's escaping feature for free. Please try it out and report bugs and/or improvements. [Dmitry Shachnev]: https://github.com/mitya57 +[Smarty Extension]: ../extensions/smarty.md [SmartyPants]: http://daringfireball.net/projects/smartypants/ -* The Table of Contents Extension now supports new `permalink` option +* The [Table of Contents Extension] now supports new `permalink` option for creating [Sphinx]-style anchor links. +[Table of Contents Extension]: ../extensions/toc.md [Sphinx]: http://sphinx-doc.org/ * It is now possible to enable Markdown formatting inside HTML blocks by -appending `markdown=1` to opening tag attributes. See Markdown Inside HTML -Blocks section for details. Thanks to [ryneeverett] for implementing this +appending `markdown=1` to opening tag attributes. See [Markdown Inside HTML +Blocks] section for details. Thanks to [ryneeverett] for implementing this feature. +[Markdown Inside HTML Blocks]: ../extensions/extra.md#nested-markdown-inside-html-blocks [ryneeverett]: https://github.com/ryneeverett * The code blocks now support emphasizing some of the code lines. To use this feature, specify `hl_lines` option after language name, for example (using -the Fenced Code Extension): +the [Fenced Code Extension]): ```.python hl_lines="1 3" # This line will be emphasized. @@ -60,6 +65,7 @@ the Fenced Code Extension): Thanks to [A. Jesse Jiryu Davis] for implementing this feature. +[Fenced Code Extension]: ../extensions/fenced_code_blocks.md [A. Jesse Jiryu Davis]: https://github.com/ajdavis * Various bug fixes have been made. See the diff --git a/docs/change_log/release-2.5.md b/docs/change_log/release-2.5.md index fe7a800c1..06ffeaf5e 100644 --- a/docs/change_log/release-2.5.md +++ b/docs/change_log/release-2.5.md @@ -11,20 +11,23 @@ Python-Markdown version 2.5 supports Python versions 2.7, 3.2, 3.3, and 3.4. Backwards-incompatible Changes ------------------------------ -* Python-Markdown no longer supports Python version 2.6. You must be using Python +* Python-Markdown no longer supports Python version 2.6. You must be using Python versions 2.7, 3.2, 3.3, or 3.4. [importlib]: https://pypi.python.org/pypi/importlib -* The `force_linenos` configuration 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` keyword should be used +* The `force_linenos` configuration 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. -* Both `safe_mode` and the associated `html_replacement_text` keywords will be deprecated +[CodeHilite Extension]: ../extensions/code_hilite.md +[linenums]: ../extensions/code_hilite.md#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 + "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. @@ -60,23 +63,23 @@ Backwards-incompatible Changes 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` argument was one of the positional arguments. When that argument - is removed, the two arguments following it will no longer be at the correct + 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. * 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 + 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']) @@ -92,47 +95,48 @@ Backwards-incompatible Changes See the [documentation](../reference.md#extensions) for a full explanation of the current behavior. -* The previously documented method of appending the extension configuration 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 - [`extension_configs`](../reference.md#extension_configs) keyword should - be used instead. See the [documentation](../reference.md#extension-configs) +* The previously documented method of appending the extension configuration 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 + [`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. What's New in Python-Markdown 2.5 --------------------------------- -* The Smarty Extension has had a number of additional configuration settings +* The [Smarty Extension] has had a number of additional configuration settings added, which allows one to define their own substitutions to better support - languages other than English. Thanks to [Martin Altmayer] for implementing this + languages other than English. Thanks to [Martin Altmayer] for implementing this feature. +[Smarty Extension]: ../extensions/smarty.md [Martin Altmayer]:https://github.com/MartinAltmayer -* Named Extensions (strings passed to the [`extensions`][ex] keyword of - `markdown.Markdown`) can now point to any module and/or Class on your PYTHONPATH. - While dot notation was previously supported, a module could not be at the root of - your PYTHONPATH. The name had to contain at least one dot (requiring it to be a - sub-module). This restriction no longer exists. +* Named Extensions (strings passed to the [`extensions`][ex] keyword of + `markdown.Markdown`) can now point to any module and/or Class on your PYTHONPATH. + While dot notation was previously supported, a module could not be at the root of + your PYTHONPATH. The name had to contain at least one dot (requiring it to be a + sub-module). This restriction no longer exists. - Additionally, a Class may be specified in the name. The class must be at the end of - the name (which uses dot notation from PYTHONPATH) and be separated by a colon from - the module. + Additionally, a Class may be specified in the name. The class must be at the end of + the name (which uses dot notation from PYTHONPATH) and be separated by a colon from + the module. Therefore, if you were to import the class like this: - + from path.to.module import SomeExtensionClass Then the named extension would comprise this string: "path.to.module:SomeExtensionClass" - - This allows multiple extensions to be implemented within the same module and still - accessible when the user is not able to import the extension directly (perhaps from + + This allows multiple extensions to be implemented within the same module and still + accessible when the user is not able to import the extension directly (perhaps from a template filter or the command line). - This also means that extension modules are no longer required to include the - `makeExtension` function which returns an instance of the extension class. However, + This also means that extension modules are no longer required to include the + `makeExtension` function which returns an instance of the extension class. However, if the user does not specify the class name (she only provides `"path.to.module"`) the extension will fail to load without the `makeExtension` function included in the module. Extension authors will want to document carefully what is required to @@ -140,13 +144,13 @@ What's New in Python-Markdown 2.5 [ex]: ../reference.md#extensions -* The Extension Configuration code has been refactored to make it a little easier - for extension authors to work with configuration settings. As a result, the - [`extension_configs`][ec] keyword now accepts a dictionary rather than requiring - a list of tuples. A list of tuples is still supported so no one needs to change +* The Extension Configuration code has been refactored to make it a little easier + for extension authors to work with configuration settings. As a result, the + [`extension_configs`][ec] keyword now accepts a dictionary rather than requiring + a list of tuples. A list of tuples is still supported so no one needs to change their existing code. This should also simplify the learning curve for new users. - Extension authors are encouraged to review the new methods available on the + Extension authors are encouraged to review the new methods available on the `markdown.extnesions.Extension` class for handling configuration and adjust their code going forward. The included extensions provide a model for best practices. See the [API] documentation for a full explanation. @@ -154,11 +158,11 @@ What's New in Python-Markdown 2.5 [ec]: ../reference.md#extension_configs [API]: ../extensions/api.md#configsettings -* The [Command Line Interface][cli] now accepts a `--extensions_config` (or `-c`) - option which accepts a file name and passes the parsed content of a [YAML] or +* The [Command Line Interface][cli] now accepts a `--extensions_config` (or `-c`) + option which accepts a file name and passes the parsed content of a [YAML] or [JSON] file to the [`extension_configs`][ec] keyword of the `markdown.Markdown` - class. The contents of the YAML or JSON must map to a Python Dictionary which - matches the format required by the `extension_configs` keyword. Note that + class. The contents of the YAML or JSON must map to a Python Dictionary which + matches the format required by the `extension_configs` keyword. Note that [PyYAML] is required to parse YAML files. [cli]: ../cli.md#using-extensions @@ -166,10 +170,12 @@ What's New in Python-Markdown 2.5 [JSON]: http://json.org/ [PyYAML]: http://pyyaml.org/ -* The Admonition Extension is no longer considered "experimental." +* The [Admonition Extension][ae] is no longer considered "experimental." + +[ae]: ../extensions/admonition.md * There have been various refactors of the testing framework. While those changes - will not directly effect end users, the code is being better tested which will + will not directly effect end users, the code is being better tested which will benefit everyone. * Various bug fixes have been made. See the diff --git a/docs/change_log/release-2.6.md b/docs/change_log/release-2.6.md index aeff75067..7e7f82f0e 100644 --- a/docs/change_log/release-2.6.md +++ b/docs/change_log/release-2.6.md @@ -13,11 +13,11 @@ Backwards-incompatible Changes ### `safe_mode` Deprecated -Both `safe_mode` and the associated `html_replacement_text` keywords are 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 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 +"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. @@ -62,9 +62,9 @@ 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 + 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. @@ -72,7 +72,7 @@ Then it is recommended that you change it to read something like this: 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 +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 @@ -105,19 +105,19 @@ of the current behavior. ### Extension Configuration as Part of Extension Name Deprecated -The previously documented method of appending the extension configuration options as +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) +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 Extension is pending deprecation and will raise a +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 Extension instead, which offers most of 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 @@ -125,6 +125,8 @@ 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 @@ -187,7 +189,7 @@ worked on PyPy for some time, it is now officially supported and tested on PyPy. ### YAML Style Meta-Data -The Meta-Data Extension now includes optional support for [YAML] style +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. @@ -198,12 +200,13 @@ party extension be used if you want true YAML support. See [Issue #390][#390] fo 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 ### Table of Contents Extension Refactored -The Table of Contents Extension has been refactored and some new features +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: @@ -227,23 +230,26 @@ listed below: 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 Extension has gained a new configuration option: `use_pygments`. +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 +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 +will not directly effect end users, the code is being better tested which will benefit everyone. [flake8]: https://flake8.readthedocs.io/en/latest/ diff --git a/docs/extensions/index.md b/docs/extensions/index.md index 23c4133b7..dead39f7e 100644 --- a/docs/extensions/index.md +++ b/docs/extensions/index.md @@ -13,7 +13,7 @@ To use an extension, pass it to markdown with the `extensions` keyword. See the [Library Reference](../reference.md#extensions) for more details. -From the command line, specify an extension with the `-x` option. +From the command line, specify an extension with the `-x` option. $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html @@ -26,30 +26,31 @@ See the [Command Line docs](../cli.md) or use the `--help` option for more detai Officially Supported Extensions ------------------------------- -The extensions listed below are maintained and officially supported by -the Python-Markdown team. However, no extensions ship with Python-Markdown -by default. If you would like to use any of the extensions listed below, -you will need to install each of them individually. See the documentation -for each extension for specifics in instalation and usage. +The extensions listed below are included with (at least) the most recent release +and are officially supported by Python-Markdown. Any documentation is +maintained here and all bug reports should be made to the project. If you +have a typical install of Python-Markdown, these extensions are already +available to you using the "name" listed in the second column below. Extension | "Name" ------------------------------------ | --------------- -[Extra] | `extra` -    [Abbreviations][] | `abbr` -    [Attribute Lists][] | `attr_list` -    [Definition Lists][] | `def_list` -    [Fenced Code Blocks][] | `fenced_code` -    [Footnotes][] | `footnotes` -    [Tables][] | `tables` -    [Smart Strong][] | `smart_strong` -[Admonition][] | `admonition` -[CodeHilite][] | `codehilite` -[Meta-Data] | `meta` -[New Line to Break] | `nl2br` -[Sane Lists] | `sane_lists` -[SmartyPants] | `smarty` -[Table of Contents] | `toc` -[WikiLinks] | `wikilinks` +[Extra] | `markdown.extensions.extra` +    [Abbreviations][] | `markdown.extensions.abbr` +    [Attribute Lists][] | `markdown.extensions.attr_list` +    [Definition Lists][] | `markdown.extensions.def_list` +    [Fenced Code Blocks][] | `markdown.extensions.fenced_code` +    [Footnotes][] | `markdown.extensions.footnotes` +    [Tables][] | `markdown.extensions.tables` +    [Smart Strong][] | `markdown.extensions.smart_strong` +[Admonition][] | `markdown.extensions.admonition` +[CodeHilite][] | `markdown.extensions.codehilite` +[HeaderId] | `markdown.extensions.headerid` +[Meta-Data] | `markdown.extensions.meta` +[New Line to Break] | `markdown.extensions.nl2br` +[Sane Lists] | `markdown.extensions.sane_lists` +[SmartyPants] | `markdown.extensions.smarty` +[Table of Contents] | `markdown.extensions.toc` +[WikiLinks] | `markdown.extensions.wikilinks` [Extra]: https://github.com/Python-Markdown/mdx_extra [Abbreviations]: https://github.com/Python-Markdown/mdx_abbreviations diff --git a/docs/index.md b/docs/index.md index 1bb7699a1..a123395fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,11 +3,11 @@ title: Python-Markdown Python-Markdown =============== -This is a Python implementation of John Gruber's -[Markdown](http://daringfireball.net/projects/markdown/). +This is a Python implementation of John Gruber's +[Markdown](http://daringfireball.net/projects/markdown/). It is almost completely compliant with the reference implementation, -though there are a few very minor [differences](#differences). See John's -[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) +though there are a few very minor [differences](#differences). See John's +[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) for the syntax rules. See the [installation instructions](install.md) to get started. @@ -18,8 +18,8 @@ Goals The Python-Markdown project is developed with the following goals in mind: * Maintain a Python 2 *and* Python 3 library (with an optional CLI wrapper) - suited to use in web server environments (never raise an exception, never - write to stdout, etc.) as an implementation of the markdown parser that + suited to use in web server environments (never raise an exception, never + write to stdout, etc.) as an implementation of the markdown parser that follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax) and the behavior of the original (markdown.pl) implementation as reasonably as possible (see [differences](#differences) for a few exceptions). @@ -35,15 +35,16 @@ features: * __International Input__ - Python-Markdown will accept [input](reference.md#text) in any language - supported by Unicode including bi-directional text. In fact the test suite + Python-Markdown will accept [input](reference.md#text) in any language + supported by Unicode including bi-directional text. In fact the test suite includes documents written in Russian and Arabic. * __Extensions__ - Various [extensions](extensions/index.md) are avaiable to change and/or - extend the base syntax. Additionally, a public [Extension API](extensions/api.md) - is available to write your own extensions. + Various [extensions](extensions/index.md) are provided (including + [extra](extensions/extra.md)) to change and/or extend the base syntax. + Additionally, a public [Extension API](extensions/api.md) is available + to write your own extensions. * __Output Formats__ @@ -52,59 +53,60 @@ features: * __Command Line Interface__ - In addition to being a Python Library, a + In addition to being a Python Library, a [command line script](cli.md) is available for your convenience. Differences ----------- -While Python-Markdown strives to fully implement markdown as described in the -[syntax rules](http://daringfireball.net/projects/markdown/syntax), the rules -can be interpreted in different ways and different implementations -occasionally vary in their behavior (see the +While Python-Markdown strives to fully implement markdown as described in the +[syntax rules](http://daringfireball.net/projects/markdown/syntax), the rules +can be interpreted in different ways and different implementations +occasionally vary in their behavior (see the [Babelmark FAQ](http://johnmacfarlane.net/babelmark2/faq.html#what-are-some-examples-of-interesting-divergences-between-implementations) -for some examples). Known and intentional differences found in Python-Markdown +for some examples). Known and intentional differences found in Python-Markdown are summarized below: * __Middle-Word Emphasis__ Python-Markdown defaults to ignoring middle-word emphasis. In other words, `some_long_filename.txt` will not become `somelongfilename.txt`. - This can be disabled with an extension. + This can be switched off if desired. See the + [Library Reference](reference.html#smart_emphasis) for details. * __Indentation/Tab Length__ - The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list) - clearly state that when a list item consists of multiple paragraphs, "each - subsequent paragraph in a list item **must** be indented by either 4 spaces - or one tab" (emphasis added). However, many implementations do not enforce - this rule and allow less than 4 spaces of indentation. The implementers of - Python-Markdown consider it a bug to not enforce this rule. + The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list) + clearly state that when a list item consists of multiple paragraphs, "each + subsequent paragraph in a list item **must** be indented by either 4 spaces + or one tab" (emphasis added). However, many implementations do not enforce + this rule and allow less than 4 spaces of indentation. The implementers of + Python-Markdown consider it a bug to not enforce this rule. This applies to any block level elements nested in a list, including - paragraphs, sub-lists, blockquotes, code blocks, etc. They **must** always + paragraphs, sub-lists, blockquotes, code blocks, etc. They **must** always be indented by at least four spaces (or one tab) for each level of nesting. In the event that one would prefer different behavior, - [tab_length](reference.md#tab_length) can be set to whatever length is - desired. Be warned however, as this will affect indentation for all aspects + [tab_length](reference.md#tab_length) can be set to whatever length is + desired. Be warned however, as this will affect indentation for all aspects of the syntax (including root level code blocks). * __Consecutive Lists__ While the syntax rules are not clear on this, many implementations (including the original) do not end one list and start a second list when the list marker - (asterisks, pluses, hyphens, and numbers) changes. For consistency, - Python-Markdown maintains the same behavior with no plans to change in the - foreseeable future. That said, the Sane List Extension + (asterisks, pluses, hyphens, and numbers) changes. For consistency, + Python-Markdown maintains the same behavior with no plans to change in the + foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.md) is available to provide a less surprising behavior. - + Support ------- -You may ask for help and discuss various other issues on the [mailing list][] +You may ask for help and discuss various other issues on the [mailing list][] and report bugs on the [bug tracker][]. [mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss -[bug tracker]: http://github.com/Python-Markdown/markdown/issues +[bug tracker]: http://github.com/Python-Markdown/markdown/issues