aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/extensions/api.txt27
1 files changed, 18 insertions, 9 deletions
diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index 715df6d..d11c534 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -550,10 +550,13 @@ If an extension uses any parameters that the user may want to change,
those parameters should be stored in ``self.config`` of your
``markdown.Extension`` class in the following format:
- self.config = {parameter_1_name : [value1, description1],
- parameter_2_name : [value2, description2] }
+ class MyExtension(markdown.extensions.Extension):
+ def __init__(self, *args, **kwargs):
+ self.config = {parameter_1_name : [value1, description1],
+ parameter_2_name : [value2, description2] }
+ super(MyExtension, self).__init__(*args, **kwargs)
-When stored this way the config parameters can be over-ridden from the
+When implemented this way the config parameters can be over-ridden from the
command line or at the time Markdown is initiated:
markdown.py -x myextension(SOME_PARAM=2) inputfile.txt > output.txt
@@ -573,8 +576,7 @@ For example:
import markdown
import myextension
- configs = {...}
- myext = myextension.MyExtension(configs=configs)
+ myext = myextension.MyExtension(option='value')
md = markdown.Markdown(extensions=[myext])
This is especially useful if you need to implement a large number of extensions
@@ -583,14 +585,21 @@ 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:
+`makeExtension` that takes `*args` and `**kwargs`. For example:
class MyExtension(markdown.extensions.Extension)
# Define extension here...
- def makeExtension(configs=None):
- return MyExtension(configs=configs)
+ def makeExtension(*args, **kwargs):
+ return MyExtension(*args, **kwargs)
+
+!!! warning
+ Previous versions of Python-Markdown expected a `config` keyword which contained
+ a dictionary (or list of tuples) of options. To maintain backward compatability,
+ the `config` keyword is given special treatment and you should avoid using "config"
+ as an option name. Additionaly, in some past situations, the `config` dict may have
+ been passed in as a positional argument. Therefore, it is sugegsted that positional
+ arguments be avoided for any othe purpose.
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.