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.