As the parser builds an [ElementTree] object which is later rendered
as Unicode text, there are also some helpers provided to make manipulation of
the tree easier. Each part of the API is discussed in its respective
-section below. You may find reading the source of some [[existing extensions]]
-helpful as well. For example, the [[footnote]] extension uses most of the
+section below. You may find reading the source of some [[Available Extensions]]
+helpful as well. For example, the [[Footnotes]] extension uses most of the
features documented here.
<h4 id="etpostprocessors">ElementTree Postprocessors</h4>
-A ElementTree Postprocessor should inherit from `markdown.Postprocessor` and over-ride
-the `run` method which takes one argument `root` and should return either
+An ElementTree Postprocessor should inherit from `markdown.Postprocessor`,
+over-ride the `run` method which takes one argument `root` and return either
that root element or a modified root element.
-For specifics on manipulating the ElementTree, see [Working with the ElementTree] below.
+For specifics on manipulating the ElementTree, see
+[Working with the ElementTree] below.
over-ride the `run` method which takes one argument `text` and returns a
-TextPostprocessors are run after the ElementTree has been serialized back into Unicode
-text. For example, this may be an appropriate place to add a table of contents
+TextPostprocessors are run after the ElementTree has been serialized back into
+Unicode text. For example, this may be an appropriate place to add a table of
<h3 id="working_with_et">Working with the ElementTree</h3>
As mentioned, the Markdown parser converts a source document to an
ElementTree object before serializing that back to Unicode text.
+[ElementTree] object before serializing that back to Unicode text.
Markdown has provided some helpers to ease that manipulation within the context
-First of all, to get access to the ElementTree module object you should use:
+First, to get access to the ElementTree module import ElementTree from
+``markdown`` rather than importing it directly. This will ensure you are using
+the same version of ElementTree as markdown. The module is named ``etree``
+ from markdown import etree
-It's try to import ElementTree from any known places, first as standard Python
-cElementTree/ElementTree module, then as separately installed cElementTree/ElementTree.
-Another thing you need to know is that all text data, included in <inline> tag will be
-processed later with [InlinePatterns].
+``markdown.etree`` tries to import ElementTree from any known location, first
+as a standard library module (from ``xml.etree`` in Python 2.5), then as a third
+party package (``Elementree``). In each instance, ``cElementTree`` is tried
+first, then ``ElementTree`` if the faster C implementation is not available on
-Example below show basic ElementTree functionality:
+Sometimes you may want text inserted into an element to be parsed by
+[InlinePatterns]. In such a situation, simply insert the text into an
+`inline` tag and the text will be automatically run through the InlinePatterns.
+Here's a basic example which creates an HTML table (note that the contents of
+the second cell (``td2``) will be run through InlinePatterns latter):
table = etree.Element("table")
table.set("cellpadding", "2") # Set cellpadding to 2
- tr = etree.SubElement(table, "tr") # Added child tr to table
- td = etree.SubElement(tr, "td") # Added child td to tr
- td.text = "Cell content" # Added text content to td element
+ tr = etree.SubElement(table, "tr") # Add child tr to table
+ td1 = etree.SubElement(tr, "td") # Add child td1 to tr
+ td1.text = "Cell content" # Add plain text content to td1 element
+ td2 = etree.SubElement(tr, "td") # Add second td to tr
+ inline = etree.SubElement(td2, "inline") # Add an inline element to td2
+ inline.text = "Some *text* with **inline** formatting." # Add markup text
table.tail = "Text after table" # Added text after table Element
- print etree.tostring(table) # Serialized our table
-Now let's write a simple ElementTree Postprocessor, that will add "class" attribute
+You can also manipulate an existing tree. Consider the following example which
+adds a ``class`` attribute to all ``a`` elements:
- class AttrPostprocessor(markdown.Postprocessor):
- def _findElement(self, element, name):
- find elements with @name and return list
- * element: ElementTree Element
- * name: tag name to search
+ def set_link_class(self, element):
- result += self._findElement(child, name)
+ child.set("class", "myclass") #set the class attribute
+ set_link_class(child) # run recursively on children
- for element in self._findElement(root, "a"):
- element.set("class", "MyClass") # Set "class" atribute
-For more information about working with ElementTree visit
-ElementTree [official site](http://effbot.org/zone/element-index.htm).
+For more information about working with ElementTree see the ElementTree
<h3 id="integrating_into_markdown">Integrating Your Code Into Markdown
[Config Settings]: #configsettings