aboutsummaryrefslogtreecommitdiffstats
path: root/docs/reference.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/reference.txt')
-rw-r--r--docs/reference.txt64
1 files changed, 50 insertions, 14 deletions
diff --git a/docs/reference.txt b/docs/reference.txt
index bd837ff..8117e69 100644
--- a/docs/reference.txt
+++ b/docs/reference.txt
@@ -55,24 +55,60 @@ The following options are available on the `markdown.markdown` function:
* __`extensions`__{: #extensions }: A list of extensions.
- Python-Markdown provides an API for third parties to write extensions to
- the parser adding their own additions or changes to the syntax. A few
- commonly used extensions are shipped with the markdown library. See
- the [extension documentation](extensions/index.html) for a list of
- available extensions.
-
- The list of extensions may contain instances of extensions or strings of
- extension names. If an extension name is provided as a string, the
- extension must be importable as a python module either within the
- `markdown.extensions` package or on your PYTHONPATH with a name starting
- with `mdx_`, followed by the name of the extension. Thus,
- `extensions=['extra']` will first look for the module
- `markdown.extensions.extra`, then a module named `mdx_extra`.
+ Python-Markdown provides an [API](extensions/api.html) for third parties to
+ write extensions to the parser adding their own additions or changes to the
+ syntax. A few commonly used extensions are shipped with the markdown
+ library. See the [extension documentation](extensions/index.html) for a
+ list of available extensions.
+
+ The list of extensions may contain instances of extensions and/or strings
+ of extension names.
+
+ extensions=[MyExtension(), 'path.to.my.ext', 'extra']
+
+ When passing in extension instances, each class instance must be a subclass
+ of `markdown.extensions.Extension` and any configuration options should be
+ defined when initiating the class instance rather than using the
+ [extension_configs](#extension_configs) keyword. For example:
+
+ from markdown.extensions import Extension
+ class MyExtension(Extension):
+ # define your extension here...
+
+ markdown.markdown(text, extensions=[MyExtension(configs={'option': 'value'}))
+
+ If an extension name is provided as a string, the extension must be
+ importable as a python module on your PYTHONPATH. Python's dot notation is
+ supported. Therefore, to import the 'extra' extension, one could do
+ `extensions=['markdown.extensions.extra']` However, if no dots are provided
+ in the string (`extensions=['extra']`) Markdown will first look for the
+ module `markdown.extensions.extra` (the built-in extension), then a module
+ named `mdx_extra` ('mdx_' will be appended to the beginning of the string)
+ at the root of your PYTHONPATH.
+
+ When loading an extension by name (as a sting), you may either pass in
+ configuration settings to the extension using the
+ [extension_configs](#extension_configs) keyword or by appending the
+ settings to the name in the following format:
+
+ extensions=['name(option1=value,option2=value)']
+
+ Note that there are no quotes or whitespace in the above format, which
+ severely limits how it can be used. For more complex settings, it is
+ suggested that the [extension_configs](#extension_configs) keyword
+ be used or an instance of a class be passed in.
+
+ See the documentation of the [Extension API](extensions/api.html) for
+ assistance in creating extensions.
* __`extension_configs`__{: #extension_configs }: A dictionary of
configuration settings for extensions.
- The dictionary must be of the following format:
+ Any configuration settings will only be passed to extensions loaded by name
+ (as a string). When loading extensions as class instances, pass the
+ configuration settings directly to the class when initializing it.
+
+ The dictionary of configuration settings must be in the following format:
extension_configs = {'extension_name_1':
[