aboutsummaryrefslogtreecommitdiffstats
path: root/docs/writing_extensions.txt
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2008-08-12 23:03:26 -0400
committerWaylan Limberg <waylan@gmail.com>2008-08-12 23:03:26 -0400
commit88c72d709be87321b736778d19d9277db02422a8 (patch)
tree98a83a62ba95b4b12e7739ee5713395dece15e48 /docs/writing_extensions.txt
parent871b335b300295e264124db2f3428dbd8282949b (diff)
downloadmarkdown-88c72d709be87321b736778d19d9277db02422a8.tar.gz
markdown-88c72d709be87321b736778d19d9277db02422a8.tar.bz2
markdown-88c72d709be87321b736778d19d9277db02422a8.zip
Added notes on registerExtension and reset as well as the new markdown_extensions package among a few other minor edits.
Diffstat (limited to 'docs/writing_extensions.txt')
-rwxr-xr-xdocs/writing_extensions.txt64
1 files changed, 55 insertions, 9 deletions
diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt
index 5f0ff01..df17698 100755
--- a/docs/writing_extensions.txt
+++ b/docs/writing_extensions.txt
@@ -24,6 +24,7 @@ features documented here.
* [Working with the ElementTree][]
* [Integrating your code into Markdown][]
* [extendMarkdown][]
+ * [registerExtension][]
* [Config Settings][]
* [makeExtension][]
@@ -277,11 +278,46 @@ arguments:
Contains all the various global variables within the markdown module.
Of course, with access to those items, theoretically you have the option to
-changing anything through various monkeypatching techniques. However, you should
-be aware that the various undocumented or private parts of markdown may change
-without notice and your monkeypatches may no longer work. Therefore, what you
-really should be doing is inserting processors and patterns into the markdown
-pipeline.
+changing anything through various [monkey_patching][] techniques. In fact, this
+is how both the [[HeaderId]] and [[CodeHilite]] extensions work. However, you
+should be aware that the various undocumented or private parts of markdown may
+change without notice and your monkey_patches may break with a new release.
+Therefore, what you really should be doing is inserting processors and patterns
+into the markdown pipeline. Consider yourself warned.
+
+[monkey_patching]: http://en.wikipedia.org/wiki/Monkey_patch
+
+<h4 id="registerextension">registerExtension</h4>
+
+Some extensions may need to have their state reset between multiple runs of the
+Markdown class. For example, consider the following use of the [[Footnotes]]
+extension:
+
+ md = markdown.Markdown(extensions=['footnotes'])
+ html1 = md.convert(text_with_footnote)
+ md.reset()
+ html2 = md.convert(text_without_footnote)
+
+Without calling ``reset``, the footnote definitions from the first document will
+be inserted into the second document as they are still stored within the class
+instance. Therefore the ``Extension`` class needs to define a ``reset`` method
+that will reset the state of the extension (i.e.: ``self.footnotes = {}``).
+However, as many extensions do not have a need for ``reset``, ``reset`` is only
+called on extensions that are registered.
+
+To register an extension, call ``md.registerExtension`` from within your
+``extendMarkdown`` method:
+
+
+ def extendMarkdown(self, md, md_globals):
+ md.registerExtension(self)
+ # insert processors and patterns here
+
+Then, each time ``reset`` is called on the Markdown instance, the ``reset``
+method of each registered extension will be called as well. You should also
+note that ``reset`` will be called on each registered extension after it is
+initialized the first time. Keep that in mind when over-riding the extension's
+``reset`` method.
<h4 id="configsettings">Config Settings</h4>
@@ -308,7 +344,8 @@ 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:
+and returns an instance of the extension. An example from the footnote
+extension:
def makeExtension(configs=None) :
return FootnoteExtension(configs=configs)
@@ -317,11 +354,19 @@ 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.
-However, Markdown will also accept an already existing instance of an extension.For example:
+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, mdx_myextension
+ import markdown
+ import myextension
configs = {...}
- myext = mdx_myextension.MyExtension(configs=configs)
+ 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
@@ -337,6 +382,7 @@ than one residing in a module.
[Working with the ElementTree]: #working_with_et
[Integrating your code into Markdown]: #integrating_into_markdown
[extendMarkdown]: #extendmarkdown
+[registerExtension]: #registerextension
[Config Settings]: #configsettings
[makeExtension]: #makeextension
[ElementTree]: http://effbot.org/zone/element-index.htm