aboutsummaryrefslogtreecommitdiffstats
path: root/docs/extensions
diff options
context:
space:
mode:
Diffstat (limited to 'docs/extensions')
-rw-r--r--docs/extensions/abbreviations.txt2
-rw-r--r--docs/extensions/api.txt62
-rw-r--r--docs/extensions/attr_list.txt12
-rw-r--r--docs/extensions/code_hilite.txt30
-rw-r--r--docs/extensions/definition_lists.txt4
-rw-r--r--docs/extensions/extra.txt5
-rw-r--r--docs/extensions/index.txt79
-rw-r--r--docs/extensions/wikilinks.txt6
8 files changed, 103 insertions, 97 deletions
diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.txt
index fa38f50..21d90bf 100644
--- a/docs/extensions/abbreviations.txt
+++ b/docs/extensions/abbreviations.txt
@@ -56,4 +56,4 @@ To use with other extensions, just add them to the list, like this:
Abbreviations can also be called from the command line using Markdown's `-x`
parameter, like so:
- markdown.py -x abbr source.txt > output.html
+ python -m markdown -x abbr source.txt > output.html
diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index 69fb68e..ac840f9 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -562,27 +562,10 @@ values, and should be converted at run time. For example:
### makeExtension {: #makeextension }
-Each extension should ideally be placed in its own module starting
-with the ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must
-provide a module-level function called ``makeExtension`` that takes
-an optional parameter consisting of a dictionary of configuration over-rides
-and returns an instance of the extension. An example from the footnote
-extension:
-
- def makeExtension(configs=None) :
- return FootnoteExtension(configs=configs)
-
-By following the above example, when Markdown is passed the name of your
-extension as a string (i.e.: ``'footnotes'``), it will automatically import
-the module and call the ``makeExtension`` function initiating your extension.
+As noted in the [library reference] an instance of an extension can be passed
+directly to Markdown. In fact, this is the prefered way to use third-party
+extensions.
-You may have noted that the extensions packaged with Python-Markdown do not
-use the ``mdx_`` prefix in their module names. This is because they are all
-part of the ``markdown.extensions`` package. Markdown will first try to import
-from ``markdown.extensions.extname`` and upon failure, ``mdx_extname``. If both
-fail, Markdown will continue without the extension.
-
-However, Markdown will also accept an already existing instance of an extension.
For example:
import markdown
@@ -591,8 +574,42 @@ For example:
myext = myextension.MyExtension(configs=configs)
md = markdown.Markdown(extensions=[myext])
-This is useful if you need to implement a large number of extensions with more
-than one residing in a module.
+This is especially useful if you need to implement a large number of extensions
+with more than one residing in a module.
+
+However, for historical reasons, Markdown also accepts "named" third party
+extensions. In that case, only one extension can be defined per module
+and that extension must define a module-level function called
+`makeExtension` that takes an optional parameter consisting of a dictionary
+of configuration over-rides and returns an instance of the extension. For example:
+
+ class MyExtension(markdown.extensions.Extension)
+ # Define extension here...
+
+ def makeExtension(configs=None):
+ return MyExtension(configs=configs)
+
+When Markdown is passed the "name" of your extension as a string, it will import
+the module and call the `makeExtension` function to initiate your extension.
+
+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 extensions with your
+library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py`
+contains the `makeExtension` function and the `mylib` directory is on the PYTHONPATH.
+
+You may have noted that the extensions packaged with Python-Markdown do not
+use Python's dot notation in their names. This is because they are
+all part of the `markdown.extensions` package. If a "name" contains any dots
+(`.`), then it will be imported as-is. Otherwise, Markdown will first try to
+import from `markdown.extensions.extname` and upon failure, `mdx_extname` where
+`"extname"` is the "name" passed to Markdown.
+
+!!! Note
+ While the `mdx_extname` method of naming extensions is still supported, it
+ remains solely for historical reasons to support the various existing
+ third-party extensions. This method is discouraged going forward and support
+ may be removed in a future release.
[Preprocessors]: #preprocessors
[InlinePatterns]: #inlinepatterns
@@ -610,3 +627,4 @@ than one residing in a module.
[Available Extensions]: index.html
[Footnotes]: footnotes.html
[Definition Lists]: definition_lists.html
+[library reference]: ../reference.html
diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt
index 4134a82..54a61d0 100644
--- a/docs/extensions/attr_list.txt
+++ b/docs/extensions/attr_list.txt
@@ -26,14 +26,14 @@ The basic syntax was inspired by [Maruku][]'s Attribute List feature.
An example attribute list might look like this:
- {: #someid .someclass somekey='some values' }
+ {: #someid .someclass somekey='some value' }
-A word which starts with a hash `#` will set the id of an element.
+A word which starts with a hash (`#`) will set the id of an element.
-A word which starts with a dot `.` will add to the list of classes assigned to
-an element.
+A word which starts with a dot (`.`) will be added to the list of classes
+assigned to an element.
-A key/value pair will assign that pair to the element.
+A key/value pair (`somekey='some value'`) will assign that pair to the element.
Be aware that while the dot syntax will add to a class, using key/value pairs
will always override the previously defined attribute. Consider the following:
@@ -42,7 +42,7 @@ will always override the previously defined attribute. Consider the following:
The above example would result in the following attributes being defined:
- id="id2 class="class2 class3 class4"
+ id="id2" class="class2 class3 class4"
### Block Level ###
diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
index 31ecfbb..57f81ca 100644
--- a/docs/extensions/code_hilite.txt
+++ b/docs/extensions/code_hilite.txt
@@ -30,8 +30,9 @@ language. When that fails, the code block will display as un-highlighted code.
[dl]: http://pygments.org/download/
[documentation]: http://pygments.org/docs
-**Note:** The css and/or javascript is not included as part of this extension
-but shall always be provided by the end user.
+!!! Note
+ The css and/or javascript is not included as part of this extension
+ but shall always be provided by the end user.
Syntax
------
@@ -42,11 +43,11 @@ the code block. There are three ways to tell the hiliter what language the code
block contains and each one has a different result.
!!! Note
-The format of the language identifier only effects the display of line numbers
-if `linenums` is set to `None` (the default). If set to `True` or `False`
-(see [Usage](#usage) below) the format of the identifier has no effect on the
-display of line numbers -- it only serves as a means to define the language
-of the code block.
+ The format of the language identifier only effects the display of line numbers
+ if `linenums` is set to `None` (the default). If set to `True` or `False`
+ (see [Usage](#usage) below) the format of the identifier has no effect on the
+ display of line numbers -- it only serves as a means to define the language
+ of the code block.
[syntax]: http://daringfireball.net/projects/markdown/syntax#precode
@@ -93,10 +94,8 @@ Will result in:
###When No Language is Defined
CodeHilite is completely backward compatible so that if a code block is
-encountered that does not define a language, the block is simple wrapped in
-`<pre>` tags and output. Note: one exception would be that the Pygments
-highlighting engine will try to guess the language. Upon failure, the same
-behavior will happen as described here.
+encountered that does not define a language, the block is simply wrapped in
+`<pre>` tags and output.
# Code goes here ...
@@ -106,9 +105,14 @@ Will result in:
Lets see the source for that:
- <div class="codehilite" ><pre><code># Code goes here ...
+ <div class="codehilite"><pre><code># Code goes here ...
</code></pre></div>
+!!! Note
+ When no language is defined, the Pygments highlighting engine will try to guess
+ the language (unless `guess_lang` is set to `False`). Upon failure, the same
+ behavior will happen as described above.
+
Usage
-----
@@ -131,7 +135,7 @@ SheBangs (`#!`) for language identification, set `linenums` to `False`.
... )
If you want to prevent Pygments from guessing the language, only highlighting
-blocks when you explicitly request it, set the `guess_lang` setting to 'False'.
+blocks when you explicitly request it, set the `guess_lang` setting to `False`.
>>> html = markdown.markdown(text,
... extensions=['codehilite(guess_lang=False)']
diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.txt
index 53f14a0..a5ba393 100644
--- a/docs/extensions/definition_lists.txt
+++ b/docs/extensions/definition_lists.txt
@@ -10,7 +10,7 @@ Definition Lists
Summary
-------
-The Definition List Extension adds the ability to create definition list in
+The Definition List Extension adds the ability to create definition lists in
Markdown documents.
This extension is included in the standard Markdown library.
@@ -58,4 +58,4 @@ To use with other extensions, just add them to the list, like this:
The extension can also be called from the command line using Markdown's `-x`
parameter:
- markdown.py -x def_list source.txt > output.html
+ python -m markdown -x def_list source.txt > output.html
diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt
index adafe07..d747496 100644
--- a/docs/extensions/extra.txt
+++ b/docs/extensions/extra.txt
@@ -34,11 +34,6 @@ From the Python interpreter:
>>> import markdown
>>> html = markdown.markdown(text, ['extra'])
-In the unlikely event that one or more of the supported extensions are not
-available for import, Markdown will simply continue without that
-extension. If you would like to be notified of such failures,
-you may set Python-Markdown's logger level to "WARN".
-
There may be [additional extensions](index.html) that are distributed with
Python-Markdown that are not included here in Extra. The features
of those extensions are not part of PHP Markdown Extra, and
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 5cbdd7d..99ca8c7 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -12,16 +12,22 @@ 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
actual source files.
-To use an extension, pass it's name to markdown with the `extensions` keyword.
-See the [Library Reference](../reference.html#extensions) for more details.
+To use an extension, pass it to markdown with the `extensions` keyword.
+
+ markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'footnotes'])
- markdown.markdown(some_text, extensions=['footnotes', 'nl2br'])
+See the [Library Reference](../reference.html#extensions) for more details.
-From the command line, specify an extension with the `-x` option. See the
-[Command Line docs](../cli.html) or use the `--help` option for more details.
+From the command line, specify an extension with the `-x` option.
python -m markdown -x footnotes -x tables input.txt > output.html
+See the [Command Line docs](../cli.html) or use the `--help` option for more details.
+
+!!! seealso "See Also"
+ If you would like to write your own extensions, see the
+ [Extension API](api.html) for details.
+
Officially Supported Extensions
-------------------------------
@@ -29,25 +35,29 @@ 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.
-
-### Markdown Extra
-
-You can enable **all** these extensions just as if it was a single
-`extra` extension. Example:
-
- markdown.markdown(some_text, extensions=['extra', 'codehilite'])
-
-Extension | Name in Python-Markdown
---------- | -----------------------
-[Abbreviations][] | `abbr`
-[Attribute Lists][] | `attr_list`
-[Definition Lists][] | `def_list`
-[Fenced Code Blocks][] | `fenced_code`
-[Footnotes][] | `footnotes`
-[Tables][] | `tables`
-[Smart Strong][] | `smart_strong`
-
+available to you using the "name" listed in the second column below.
+
+Extension | "Name"
+------------------------------------ | ---------------
+[Extra] | `extra`
+&nbsp; &nbsp; [Abbreviations][] | `abbr`
+&nbsp; &nbsp; [Attribute Lists][] | `attr_list`
+&nbsp; &nbsp; [Definition Lists][] | `def_list`
+&nbsp; &nbsp; [Fenced Code Blocks][] | `fenced_code`
+&nbsp; &nbsp; [Footnotes][] | `footnotes`
+&nbsp; &nbsp; [Tables][] | `tables`
+&nbsp; &nbsp; [Smart Strong][] | `smart_strong`
+[Admonition][] | `admonition`
+[CodeHilite][] | `codehilite`
+[HTML Tidy][] | `html_tidy`
+[HeaderId] | `headerid`
+[Meta-Data] | `meta`
+[New Line to Break] | `nl2br`
+[Sane Lists] | `sane_lists`
+[Table of Contents] | `toc`
+[WikiLinks] | `wikilinks`
+
+[Extra]: extra.html
[Abbreviations]: abbreviations.html
[Attribute Lists]: attr_list.html
[Definition Lists]: definition_lists.html
@@ -55,24 +65,6 @@ Extension | Name in Python-Markdown
[Footnotes]: footnotes.html
[Tables]: tables.html
[Smart Strong]: smart_strong.html
-
-### Other extensions
-
-There are also some extensions that are not included in Markdown Extra
-but come in the standard Python-Markdown library.
-
-Extension | Name in Python-Markdown
---------- | -----------------------
-[Admonition][] | `admonition`
-[CodeHilite][] | `codehilite`
-[HTML Tidy][] | `html_tidy`
-[HeaderId] | `headerid`
-[Meta-Data] | `meta`
-[New Line to Break] | `nl2br`
-[Sane Lists] | `sane_lists`
-[Table of Contents] | `toc`
-[WikiLinks] | `wikilinks`
-
[Admonition]: admonition.html
[CodeHilite]: code_hilite.html
[HTML Tidy]: html_tidy.html
@@ -92,6 +84,3 @@ extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extension
is maintained on the wiki for your convenience. The Python-Markdown team
offers no official support for these extensions. Please see the developer of
each extension for support.
-
-If you would like to write your own extensions, see the
-[Extensions API](api.html) for details.
diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt
index 5f6d20e..ed191e3 100644
--- a/docs/extensions/wikilinks.txt
+++ b/docs/extensions/wikilinks.txt
@@ -54,7 +54,7 @@ From the Python interpreter:
The default behavior is to point each link to the document root of the current
domain and close with a trailing slash. Additionally, each link is assigned to
the html class `wikilink`. This may not always be desirable. Therefore, one can
-customize that behavior within Python code. Three settings are provided to
+customize that behavior within Python code. Four settings are provided to
change the default behavior:
1. **base_url**: String to append to beginning of URL.
@@ -108,7 +108,7 @@ Would cause all wikilinks to be assigned to the class `myclass`.
The same options can be used on the command line as well:
- python markdown.py -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt
+ python -m markdown -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt
Some may prefer the more complex format when calling the `Markdown` class directly:
@@ -133,7 +133,7 @@ meta-data keywords are:
* `wiki_end_url`
* `wiki_html_class`
-When used, the meta-data will override the settings provided through the
+When used, the meta-data will override the settings provided through the
`extension_configs` interface.
This document: