aboutsummaryrefslogtreecommitdiffstats
path: root/docs/extensions
diff options
context:
space:
mode:
Diffstat (limited to 'docs/extensions')
-rw-r--r--docs/extensions/abbreviations.md4
-rw-r--r--docs/extensions/admonition.md11
-rw-r--r--docs/extensions/api.md77
-rw-r--r--docs/extensions/attr_list.md4
-rw-r--r--docs/extensions/code_hilite.md4
-rw-r--r--docs/extensions/definition_lists.md4
-rw-r--r--docs/extensions/extra.md2
-rw-r--r--docs/extensions/fenced_code_blocks.md4
-rw-r--r--docs/extensions/footnotes.md5
-rw-r--r--docs/extensions/index.md48
-rw-r--r--docs/extensions/meta_data.md6
-rw-r--r--docs/extensions/nl2br.md6
-rw-r--r--docs/extensions/sane_lists.md4
-rw-r--r--docs/extensions/smart_strong.md13
-rw-r--r--docs/extensions/smarty.md6
-rw-r--r--docs/extensions/tables.md4
-rw-r--r--docs/extensions/toc.md6
-rw-r--r--docs/extensions/wikilinks.md4
18 files changed, 125 insertions, 87 deletions
diff --git a/docs/extensions/abbreviations.md b/docs/extensions/abbreviations.md
index d580d56..eed8788 100644
--- a/docs/extensions/abbreviations.md
+++ b/docs/extensions/abbreviations.md
@@ -39,7 +39,7 @@ is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>
Usage
-----
-See [Extensions](index.md) for general extension usage, specify `markdown.extensions.abbr`
-as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `abbr` as the name
+of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/admonition.md b/docs/extensions/admonition.md
index 26e6299..a6a8398 100644
--- a/docs/extensions/admonition.md
+++ b/docs/extensions/admonition.md
@@ -78,7 +78,14 @@ rST suggests the following `types`, but you're free to use whatever you want:
Styling
-------
-There is no CSS included as part of this extension. Look up the default
-[Sphinx][sphinx] theme if you need inspiration.
+There is no CSS included as part of this extension. Check out the default
+[Sphinx][sphinx] theme for inspiration.
[sphinx]: http://sphinx.pocoo.org/
+
+## Usage
+
+See [Extensions](index.md) for general extension usage. Use `admonition` as the
+name of the extension.
+
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/api.md b/docs/extensions/api.md
index 3d8cfff..cba4ea7 100644
--- a/docs/extensions/api.md
+++ b/docs/extensions/api.md
@@ -639,7 +639,7 @@ following methods available to assist in working with configuration settings:
Sets multiple configuration settings given a dict of key/value pairs.
-### `makeExtension` {: #makeextension }
+### Naming an Extension { #naming_an_extension }
As noted in the [library reference] an instance of an extension can be passed
directly to Markdown. In fact, this is the preferred way to use third-party
@@ -649,36 +649,70 @@ For example:
```python
import markdown
-import myextension
-myext = myextension.MyExtension(option='value')
-md = markdown.Markdown(extensions=[myext])
+from path.to.module import MyExtention
+md = markdown.Markdown(extensions=[MyExtension(option='value')])
```
-Markdown also accepts "named" third party extensions for those occasions when it
-is impractical to import an extension directly (from the command line or from
-within templates).
+However, Markdown also accepts "named" third party extensions for those
+occasions when it is impractical to import an extension directly (from the
+command line or from within templates). A "name" can either be a registered
+[entry point](#entry_point) or a string using Python's [dot
+notation](#dot_notation).
-The "name" of your extension must be a string consisting of the importable path to
-your module using Python's dot notation. Therefore, if you are providing a library
-to your users and would like to include a custom markdown extension within your
-library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py`
-contains the extension and the `mylib` directory is on the PYTHONPATH.
+#### Entry Point { #entry_point }
+
+[Entry points] are defined in a Python package's `setup.py` script. The script
+must use [setuptools] to support entry points. Python-Markdown extensions must
+be assigned to the `markdown.extensions` group. An entry point definition might
+look like this:
+
+```python
+from setuptools import setup
+
+setup(
+ # ...
+ entry_points={
+ 'markdown.extensions': ['myextension = path.to.module:MyExtension']
+ }
+)
+```
+
+After a user installs your extension using the above script, they could then
+call the extension using the `myextension` string name like this:
+
+```python
+markdown.markdown(text, extensions=['myextention'])
+```
+
+Note that if two or more entry points within the same group are assigned the
+same name, Python-Markdown will only ever use the first one found and ignore all
+others. Therefore, be sure to give your extension a unique name.
+
+For more information on writing `setup.py` scripts, see the Python documentation
+on [Packaging and Distributing Projects].
+
+#### Dot Notation { #dot_notation }
+
+If an extension does not have a registered entry point, Python's dot notation
+may be used instead. The extension must be installed as a Python module on your
+PYTHONPATH. Generally, a class should be specified in the name. The class must
+be at the end of the name and be separated by a colon from the module.
-The string can also include the name of the class separated by a colon.
Therefore, if you were to import the class like this:
```python
-from path.to.module import SomeExtensionClass
+from path.to.module import MyExtention
```
-Then the named extension would comprise this string:
+Then the extension can be loaded as follows:
```python
-"path.to.module:SomeExtensionClass"
+markdown.markdown(text, extensions=['path.to.module:MyExtention'])
```
You do not need to do anything special to support this feature. As long as your
-extension class is able to be imported, a user can include it with the above syntax.
+extension class is able to be imported, a user can include it with the above
+syntax.
The above two methods are especially useful if you need to implement a large
number of extensions with more than one residing in a module. However, if you do
@@ -697,9 +731,9 @@ def makeExtension(**kwargs):
return MyExtension(**kwargs)
```
-When Markdown is passed the "name" of your extension as a dot notation string,
-it will import the module and call the `makeExtension` function to initiate your
-extension.
+When Markdown is passed the "name" of your extension as a dot notation string
+that does not include a class (for example `path.to.module`), it will import the
+module and call the `makeExtension` function to initiate your extension.
[Preprocessors]: #preprocessors
[Inline Patterns]: #inlinepatterns
@@ -718,3 +752,6 @@ extension.
[Footnotes]: https://github.com/Python-Markdown/mdx_footnotes
[Definition Lists]: https://github.com/Python-Markdown/mdx_definition_lists
[library reference]: ../reference.md
+[setuptools]: https://packaging.python.org/key_projects/#setuptools
+[Entry points]: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins
+[Packaging and Distributing Projects]: https://packaging.python.org/tutorials/distributing-packages/
diff --git a/docs/extensions/attr_list.md b/docs/extensions/attr_list.md
index 7b2e19f..9fc8b6e 100644
--- a/docs/extensions/attr_list.md
+++ b/docs/extensions/attr_list.md
@@ -92,7 +92,7 @@ The above results in the following output:
## Usage
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.attr_list` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `attr_list` as the
+name of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md
index 6490dcc..552a82d 100644
--- a/docs/extensions/code_hilite.md
+++ b/docs/extensions/code_hilite.md
@@ -168,8 +168,8 @@ Lets see the source for that:
## Usage
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.codehilite` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `codehilite` as the
+name of the extension.
See the [Library Reference](../reference.md#extensions) for information about
configuring extensions.
diff --git a/docs/extensions/definition_lists.md b/docs/extensions/definition_lists.md
index e9f8984..0d42fd0 100644
--- a/docs/extensions/definition_lists.md
+++ b/docs/extensions/definition_lists.md
@@ -46,7 +46,7 @@ the family Rosaceae.</dd>
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.def_list` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `def_list` as the
+name of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/extra.md b/docs/extensions/extra.md
index 0639d3d..3d9f374 100644
--- a/docs/extensions/extra.md
+++ b/docs/extensions/extra.md
@@ -26,7 +26,7 @@ From the Python interpreter:
```pycon
>>> import markdown
->>> html = markdown.markdown(text, ['markdown.extensions.extra'])
+>>> html = markdown.markdown(text, ['extra'])
```
There may be [additional extensions](index.md) that are distributed with
diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md
index b7a657e..96fe786 100644
--- a/docs/extensions/fenced_code_blocks.md
+++ b/docs/extensions/fenced_code_blocks.md
@@ -110,7 +110,7 @@ The lines can be specified with PHP Extra's syntax:
## Usage
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.fenced_code` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `fenced_code` as
+the name of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md
index aaff184..4df12a1 100644
--- a/docs/extensions/footnotes.md
+++ b/docs/extensions/footnotes.md
@@ -63,8 +63,8 @@ is indented consistently and any errors are more easily discernible by the autho
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.footnotes` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `footnotes` as the
+name of the extension.
See the [Library Reference](../reference.md#extensions) for information about
configuring extensions.
@@ -90,4 +90,3 @@ The following options are provided to configure the output:
The text string for the `title` HTML attribute of the footnote definition link.
`%d` will be replaced by the footnote number. Defaults to `Jump back to
footnote %d in the text`
-
diff --git a/docs/extensions/index.md b/docs/extensions/index.md
index 34f8084..3d98760 100644
--- a/docs/extensions/index.md
+++ b/docs/extensions/index.md
@@ -1,7 +1,6 @@
title: Extensions
-Available Extensions
-====================
+# Extensions
Python Markdown offers a flexible extension mechanism, which makes it possible
to change and/or extend the behavior of the parser without having to edit the
@@ -10,7 +9,7 @@ actual source files.
To use an extension, pass it to markdown with the `extensions` keyword.
```python
-markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes'])
+markdown.markdown(some_text, extensions=[MyExtClass(), 'myext', 'path.to.my.ext:MyExtClass'])
```
See the [Library Reference](../reference.md#extensions) for more details.
@@ -18,7 +17,7 @@ See the [Library Reference](../reference.md#extensions) for more details.
From the command line, specify an extension with the `-x` option.
```bash
-python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html
+python -m markdown -x myext -x path.to.module:MyExtClass input.txt > output.html
```
See the [Command Line docs](../cli.md) or use the `--help` option for more details.
@@ -34,27 +33,26 @@ 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] | `markdown.extensions.extra`
-&nbsp; &nbsp; [Abbreviations][] | `markdown.extensions.abbr`
-&nbsp; &nbsp; [Attribute Lists][] | `markdown.extensions.attr_list`
-&nbsp; &nbsp; [Definition Lists][] | `markdown.extensions.def_list`
-&nbsp; &nbsp; [Fenced Code Blocks][] | `markdown.extensions.fenced_code`
-&nbsp; &nbsp; [Footnotes][] | `markdown.extensions.footnotes`
-&nbsp; &nbsp; [Tables][] | `markdown.extensions.tables`
-&nbsp; &nbsp; [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`
+available to you using the "Entry Point" name listed in the second column below.
+
+Extension | Entry Point | Dot Notation
+------------------------------------ | -------------- | ------------
+[Extra] | `extra` | `markdown.extensions.extra`
+&nbsp; &nbsp; [Abbreviations][] | `abbr` | `markdown.extensions.abbr`
+&nbsp; &nbsp; [Attribute Lists][] | `attr_list` | `markdown.extensions.attr_list`
+&nbsp; &nbsp; [Definition Lists][] | `def_list` | `markdown.extensions.def_list`
+&nbsp; &nbsp; [Fenced Code Blocks][] | `fenced_code` | `markdown.extensions.fenced_code`
+&nbsp; &nbsp; [Footnotes][] | `footnotes` | `markdown.extensions.footnotes`
+&nbsp; &nbsp; [Tables][] | `tables` | `markdown.extensions.tables`
+&nbsp; &nbsp; [Smart Strong][] | `smart_strong` | `markdown.extensions.smart_strong`
+[Admonition][] | `admonition` | `markdown.extensions.admonition`
+[CodeHilite][] | `codehilite` | `markdown.extensions.codehilite`
+[Meta-Data] | `meta` | `markdown.extensions.meta`
+[New Line to Break] | `nl2br` | `markdown.extensions.nl2br`
+[Sane Lists] | `sane_lists` | `markdown.extensions.sane_lists`
+[SmartyPants] | `smarty` | `markdown.extensions.smarty`
+[Table of Contents] | `toc` | `markdown.extensions.toc`
+[WikiLinks] | `wikilinks` | `markdown.extensions.wikilinks`
[Extra]: extra.md
[Abbreviations]: abbreviations.md
diff --git a/docs/extensions/meta_data.md b/docs/extensions/meta_data.md
index 36d5e7a..29f3e0b 100644
--- a/docs/extensions/meta_data.md
+++ b/docs/extensions/meta_data.md
@@ -57,8 +57,8 @@ by Markdown.
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.meta` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `meta` as the name
+of the extension.
Accessing the Meta-Data
-----------------------
@@ -67,7 +67,7 @@ The meta-data is made available as a python Dict in the `Meta` attribute of an
instance of the Markdown class. For example, using the above document:
```pycon
->>> md = markdown.Markdown(extensions = ['markdown.extensions.meta'])
+>>> md = markdown.Markdown(extensions = ['meta'])
>>> html = md.convert(text)
>>> # Meta-data has been stripped from output
>>> print html
diff --git a/docs/extensions/nl2br.md b/docs/extensions/nl2br.md
index 4f5e611..8c53d33 100644
--- a/docs/extensions/nl2br.md
+++ b/docs/extensions/nl2br.md
@@ -20,7 +20,7 @@ Example
... Line 1
... Line 2
... """
->>> html = markdown.markdown(text, extensions=['markdown.extensions.nl2br'])
+>>> html = markdown.markdown(text, extensions=['nl2br'])
>>> print html
<p>Line 1<br />
Line 2</p>
@@ -29,7 +29,7 @@ Line 2</p>
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.nl2br` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `nl2br` as the name
+of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/sane_lists.md b/docs/extensions/sane_lists.md
index 49a7a85..81f8d84 100644
--- a/docs/extensions/sane_lists.md
+++ b/docs/extensions/sane_lists.md
@@ -71,7 +71,7 @@ In all other ways, Sane Lists should behave as normal Markdown lists.
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.sane_lists` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `sane_lists` as the
+name of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/smart_strong.md b/docs/extensions/smart_strong.md
index 1fb3c68..65c88d6 100644
--- a/docs/extensions/smart_strong.md
+++ b/docs/extensions/smart_strong.md
@@ -19,21 +19,18 @@ Example
```pycon
>>> import markdown
->>> markdown.markdown('Text with double__underscore__words.', \
- extensions=['markdown.extensions.smart_strong'])
+>>> markdown.markdown('Text with double__underscore__words.', extensions=['smart_strong'])
u'<p>Text with double__underscore__words.</p>'
->>> markdown.markdown('__Strong__ still works.', \
- extensions=['markdown.extensions.smart_strong'])
+>>> markdown.markdown('__Strong__ still works.', extensions=['smart_strong'])
u'<p><strong>Strong</strong> still works.</p>'
->>> markdown.markdown('__this__works__too__.', \
- extensions=['markdown.extensions.smart_strong'])
+>>> markdown.markdown('__this__works__too__.', extensions=['smart_strong'])
u'<p><strong>this__works__too</strong>.</p>'
```
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.smart_strong` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `smart_strong` as
+the name of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/smarty.md b/docs/extensions/smarty.md
index 9353d9b..109d78c 100644
--- a/docs/extensions/smarty.md
+++ b/docs/extensions/smarty.md
@@ -27,7 +27,7 @@ the German language:
```python
extension_configs = {
- 'markdown.extensions.smarty': {
+ 'smarty': {
'substitutions': {
'left-single-quote': '&sbquo;', # sb is not a typo!
'right-single-quote': '&lsquo;',
@@ -53,8 +53,8 @@ extension_configs = {
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.smarty` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `smarty` as the
+name of the extension.
See the [Library Reference](../reference.md#extensions) for information about
configuring extensions.
diff --git a/docs/extensions/tables.md b/docs/extensions/tables.md
index 2bea470..59693f0 100644
--- a/docs/extensions/tables.md
+++ b/docs/extensions/tables.md
@@ -52,7 +52,7 @@ will be rendered as:
Usage
-----
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.tables` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `tables` as the
+name of the extension.
This extension does not accept any special configuration options.
diff --git a/docs/extensions/toc.md b/docs/extensions/toc.md
index a1c583f..e358132 100644
--- a/docs/extensions/toc.md
+++ b/docs/extensions/toc.md
@@ -65,7 +65,7 @@ This allows one to insert the Table of Contents elsewhere in their page
template. For example:
```pycon
->>> md = markdown.Markdown(extensions=['markdown.extensions.toc'])
+>>> md = markdown.Markdown(extensions=['toc'])
>>> html = md.convert(text)
>>> page = render_some_template(context={'body': html, 'toc': md.toc})
```
@@ -73,8 +73,8 @@ template. For example:
Usage
-----
-See [Extensions](index.md) for general extension usage, specify `markdown.extensions.toc`
-as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `toc` as the name
+of the extension.
See the [Library Reference](../reference.md#extensions) for information about
configuring extensions.
diff --git a/docs/extensions/wikilinks.md b/docs/extensions/wikilinks.md
index a46265a..dd82a96 100644
--- a/docs/extensions/wikilinks.md
+++ b/docs/extensions/wikilinks.md
@@ -46,8 +46,8 @@ becomes
## Usage
-See [Extensions](index.md) for general extension usage, specify
-`markdown.extensions.wikilinks` as the name of the extension.
+See [Extensions](index.md) for general extension usage. Use `wikilinks` as the
+name of the extension.
See the [Library Reference](../reference.md#extensions) for information about
configuring extensions.