diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/using_as_module.txt | 18 | ||||
| -rw-r--r-- | docs/writing_extensions.txt | 64 |
2 files changed, 49 insertions, 33 deletions
diff --git a/docs/using_as_module.txt b/docs/using_as_module.txt index 130d0a7..9031c4e 100644 --- a/docs/using_as_module.txt +++ b/docs/using_as_module.txt @@ -39,8 +39,12 @@ class yourself and then use ``convert()`` to generate HTML: md = markdown.Markdown( extensions=['footnotes'], extension_configs= {'footnotes' : ('PLACE_MARKER','~~~~~~~~')}, - safe_mode=True, - output_format='html4' + output_format='html4', + safe_mode="replace", + html_replacement_text="--NO HTML ALLOWED--", + tab_length=8, + enable_attributes=False, + smart_emphasis=False, ) return md.convert(some_text) @@ -106,15 +110,11 @@ still create links using Markdown syntax.) * To replace HTML, set ``safe_mode="replace"`` (``safe_mode=True`` still works for backward compatibility with older versions). The HTML will be replaced - with the text defined in ``markdown.HTML_REMOVED_TEXT`` which defaults to + with the text assigned to ``html_replacement_text`` which defaults to ``[HTML_REMOVED]``. To replace the HTML with something else: - markdown.HTML_REMOVED_TEXT = "--RAW HTML IS NOT ALLOWED--" - md = markdown.Markdown(safe_mode="replace") - - **Note**: You could edit the value of ``HTML_REMOVED_TEXT`` directly in - markdown/__init__.py but you will need to remember to do so every time you - upgrade to a newer version of Markdown. Therefore, this is not recommended. + md = markdown.Markdown(safe_mode="replace", + html_replacement_text="--RAW HTML NOT ALLOWED--") * To remove HTML, set ``safe_mode="remove"``. Any raw HTML will be completely stripped from the text with no warning to the author. diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt index 3aad74a..1300d55 100644 --- a/docs/writing_extensions.txt +++ b/docs/writing_extensions.txt @@ -46,7 +46,9 @@ return either that list, or an altered list of Unicode strings. A pseudo example: - class MyPreprocessor(markdown.preprocessors.Preprocessor): + from markdown.preprocessors import Preprocessor + + class MyPreprocessor(Preprocessor): def run(self, lines): new_lines = [] for line in lines: @@ -84,9 +86,12 @@ match everything before the pattern. For an example, consider this simplified emphasis pattern: - class EmphasisPattern(markdown.inlinepatterns.Pattern): + from markdown.inlinepatterns import Pattern + from markdown.util import etree + + class EmphasisPattern(Pattern): def handleMatch(self, m): - el = markdown.etree.Element('em') + el = etree.Element('em') el.text = m.group(3) return el @@ -106,7 +111,7 @@ be almost identical, with the exception that it would create a 'strong' element. Therefore, Markdown provides a number of generic pattern classes that can provide some common functionality. For example, both emphasis and strong are implemented with separate instances of the ``SimpleTagPettern`` listed below. -Feel free to use or extend any of these Pattern classes. +Feel free to use or extend any of the Pattern classes found at `markdown.inlinepatterns`. **Generic Pattern Classes** @@ -141,7 +146,9 @@ object) and returns either that root element or a modified root element. A pseudo example: - class MyTreeprocessor(markdown.treeprocessors.Treeprocessor): + from markdown.treprocessors import Treeprocessor + + class MyTreeprocessor(Treeprocessor): def run(self, root): #do stuff return my_modified_root @@ -163,7 +170,9 @@ Postprocessors 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 to a document: - class TocPostprocessor(markdown.postprocessors.Postprocessor): + from markdown.postprocessors import Postprocessor + + class TocPostprocessor(Postprocessor): def run(self, text): return MYMARKERRE.sub(MyToc, text) @@ -302,16 +311,16 @@ of the Markdown module. 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`` -within Markdown. +the same version of ElementTree as markdown. The module is found at +``markdown.util.etree`` within Markdown. - from markdown import etree + from markdown.util import etree -``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 -your system. +``markdown.util.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 your system. Sometimes you may want text inserted into an element to be parsed by [InlinePatterns][]. In such a situation, simply insert the text as you normally @@ -319,7 +328,8 @@ would and the text will be automatically run through the InlinePatterns. However, if you do *not* want some text to be parsed by InlinePatterns, then insert the text as an ``AtomicString``. - some_element.text = markdown.AtomicString(some_text) + from markdown.util import AtomicString + some_element.text = AtomicString(some_text) 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): @@ -351,10 +361,10 @@ For more information about working with ElementTree see the ElementTree Once you have the various pieces of your extension built, you need to tell Markdown about them and ensure that they are run in the proper sequence. Markdown accepts a ``Extension`` instance for each extension. Therefore, you -will need to define a class that extends ``markdown.Extension`` and over-rides -the ``extendMarkdown`` method. Within this class you will manage configuration -options for your extension and attach the various processors and patterns to -the Markdown instance. +will need to define a class that extends ``markdown.extensions.Extension`` and +over-rides the ``extendMarkdown`` method. Within this class you will manage +configuration options for your extension and attach the various processors and +patterns to the Markdown instance. It is important to note that the order of the various processors and patterns matters. For example, if we replace ``http://...`` links with <a> elements, and @@ -367,8 +377,8 @@ a built-in instance, or replace a built-in instance with your own. <h4 id="extendmarkdown">extendMarkdown</h4> -The ``extendMarkdown`` method of a ``markdown.Extension`` class accepts two -arguments: +The ``extendMarkdown`` method of a ``markdown.extensions.Extension`` class +accepts two arguments: * **``md``**: @@ -388,6 +398,10 @@ arguments: * ``md.output_formats`` * ``md.set_output_format()`` * ``md.registerExtension()`` + * ``md.html_replacement_text`` + * ``md.tab_length`` + * ``md.enable_attributes`` + * ``md.smart_emphasis`` * **``md_globals``**: @@ -404,7 +418,9 @@ into the markdown pipeline. Consider yourself warned. A simple example: - class MyExtension(markdown.Extension): + from markdown.extensions import Extension + + class MyExtension(Extension): def extendMarkdown(self, md, md_globals): # Insert instance of 'mypattern' before 'references' pattern md.inlinePatterns.add('mypattern', MyPattern(md), '<references') @@ -447,8 +463,8 @@ The ``add()`` method accepts three arguments: Consider the following example: - >>> import markdown - >>> od = markdown.OrderedDict() + >>> from markdown.odict import OrderedDict + >>> od = OrderedDict() >>> od['one'] = 1 # The same as: od.add('one', 1, '_begin') >>> od['three'] = 3 # The same as: od.add('three', 3, '>one') >>> od['four'] = 4 # The same as: od.add('four', 4, '_end') |