diff options
Diffstat (limited to 'docs/extensions')
| -rw-r--r-- | docs/extensions/admonition.txt | 2 | ||||
| -rw-r--r-- | docs/extensions/api.txt | 368 | ||||
| -rw-r--r-- | docs/extensions/attr_list.txt | 2 | ||||
| -rw-r--r-- | docs/extensions/code_hilite.txt | 24 | ||||
| -rw-r--r-- | docs/extensions/extra.txt | 29 | ||||
| -rw-r--r-- | docs/extensions/fenced_code_blocks.txt | 6 | ||||
| -rw-r--r-- | docs/extensions/footnotes.txt | 2 | ||||
| -rw-r--r-- | docs/extensions/header_id.txt | 11 | ||||
| -rw-r--r-- | docs/extensions/meta_data.txt | 6 | ||||
| -rw-r--r-- | docs/extensions/nl2br.txt | 6 | ||||
| -rw-r--r-- | docs/extensions/smarty.txt | 6 | ||||
| -rw-r--r-- | docs/extensions/toc.txt | 6 | ||||
| -rw-r--r-- | docs/extensions/wikilinks.txt | 12 |
13 files changed, 246 insertions, 234 deletions
diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.txt index fcf866b..d68bd5d 100644 --- a/docs/extensions/admonition.txt +++ b/docs/extensions/admonition.txt @@ -26,7 +26,7 @@ Admonitions are created using the following syntax: This is the second paragraph. -`type` will be used as the CSS classname and as default title. It must be a +`type` will be used as the CSS class name and as default title. It must be a single word. So, for instance: !!! note diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt index 7987c25..66daa86 100644 --- a/docs/extensions/api.txt +++ b/docs/extensions/api.txt @@ -8,14 +8,14 @@ Writing Extensions for Python-Markdown ====================================== Python-Markdown includes an API for extension writers to plug their own -custom functionality and/or syntax into the parser. There are preprocessors +custom functionality and/or syntax into the parser. There are Preprocessors which allow you to alter the source before it is passed to the parser, inline patterns which allow you to add, remove or override the syntax of -any inline elements, and postprocessors which allow munging of the +any inline elements, and Postprocessors which allow munging of the output of the parser before it is returned. If you really want to dive in, -there are also blockprocessors which are part of the core BlockParser. +there are also Blockprocessors which are part of the core BlockParser. -As the parser builds an [ElementTree][] object which is later rendered +As the parser builds an [ElementTree][ElementTree] object which is later rendered as Unicode text, there are also some helpers provided to ease manipulation of the tree. Each part of the API is discussed in its respective section below. Additionally, reading the source of some [Available Extensions][] may be @@ -29,10 +29,10 @@ Preprocessors munge the source text before it is passed into the Markdown core. This is an excellent place to clean up bad syntax, extract things the parser may otherwise choke on and perhaps even store it for later retrieval. -Preprocessors should inherit from ``markdown.preprocessors.Preprocessor`` and -implement a ``run`` method with one argument ``lines``. The ``run`` method of +Preprocessors should inherit from `markdown.preprocessors.Preprocessor` and +implement a `run` method with one argument `lines`. The `run` method of each Preprocessor will be passed the entire source text as a list of Unicode -strings. Each string will contain one line of text. The ``run`` method should +strings. Each string will contain one line of text. The `run` method should return either that list, or an altered list of Unicode strings. A pseudo example: @@ -54,27 +54,27 @@ Inline Patterns {: #inlinepatterns } ------------------------------------ Inline Patterns implement the inline HTML element syntax for Markdown such as -``*emphasis*`` or ``[links](http://example.com)``. Pattern objects should be -instances of classes that inherit from ``markdown.inlinepatterns.Pattern`` or +`*emphasis*` or `[links](http://example.com)`. Pattern objects should be +instances of classes that inherit from `markdown.inlinepatterns.Pattern` or one of its children. Each pattern object uses a single regular expression and must have the following methods: -* **``getCompiledRegExp()``**: +* **`getCompiledRegExp()`**: Returns a compiled regular expression. -* **``handleMatch(m)``**: +* **`handleMatch(m)`**: Accepts a match object and returns an ElementTree element of a plain Unicode string. -Note that any regular expression returned by ``getCompiledRegExp`` must capture -the whole block. Therefore, they should all start with ``r'^(.*?)'`` and end -with ``r'(.*?)!'``. When using the default ``getCompiledRegExp()`` method -provided in the ``Pattern`` you can pass in a regular expression without that -and ``getCompiledRegExp`` will wrap your expression for you and set the +Note that any regular expression returned by `getCompiledRegExp` must capture +the whole block. Therefore, they should all start with `r'^(.*?)'` and end +with `r'(.*?)!'`. When using the default `getCompiledRegExp()` method +provided in the `Pattern` you can pass in a regular expression without that +and `getCompiledRegExp` will wrap your expression for you and set the `re.DOTALL` and `re.UNICODE` flags. This means that the first group of your -match will be ``m.group(2)`` as ``m.group(1)`` will match everything before the +match will be `m.group(2)` as `m.group(1)` will match everything before the pattern. For an example, consider this simplified emphasis pattern: @@ -103,23 +103,24 @@ that example pattern is not very DRY. A pattern for `**strong**` text would 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 ``SimpleTagPattern`` listed below. -Feel free to use or extend any of the Pattern classes found at `markdown.inlinepatterns`. +implemented with separate instances of the `SimpleTagPattern` listed below. +Feel free to use or extend any of the Pattern classes found at +`markdown.inlinepatterns`. **Generic Pattern Classes** -* **``SimpleTextPattern(pattern)``**: +* **`SimpleTextPattern(pattern)`**: - Returns simple text of ``group(2)`` of a ``pattern``. + Returns simple text of `group(2)` of a `pattern`. -* **``SimpleTagPattern(pattern, tag)``**: +* **`SimpleTagPattern(pattern, tag)`**: - Returns an element of type "`tag`" with a text attribute of ``group(3)`` - of a ``pattern``. ``tag`` should be a string of a HTML element (i.e.: 'em'). + Returns an element of type "`tag`" with a text attribute of `group(3)` + of a `pattern`. `tag` should be a string of a HTML element (i.e.: 'em'). -* **``SubstituteTagPattern(pattern, tag)``**: +* **`SubstituteTagPattern(pattern, tag)`**: - Returns an element of type "`tag`" with no children or text (i.e.: 'br'). + Returns an element of type "`tag`" with no children or text (i.e.: `br`). There may be other Pattern classes in the Markdown source that you could extend or use as well. Read through the source and see if there is anything you can @@ -129,13 +130,13 @@ situation. Treeprocessors {: #treeprocessors } ----------------------------------- -Treeprocessors manipulate an ElemenTree object after it has passed through the +Treeprocessors manipulate an ElementTree object after it has passed through the core BlockParser. This is where additional manipulation of the tree takes place. Additionally, the InlineProcessor is a Treeprocessor which steps through -the tree and runs the InlinePatterns on the text of each Element in the tree. +the tree and runs the Inline Patterns on the text of each Element in the tree. -A Treeprocessor should inherit from ``markdown.treeprocessors.Treeprocessor``, -over-ride the ``run`` method which takes one argument ``root`` (an Elementree +A Treeprocessor should inherit from `markdown.treeprocessors.Treeprocessor`, +over-ride the `run` method which takes one argument `root` (an ElementTree object) and either modifies that root element and returns `None` or returns a new ElementTree object. @@ -148,18 +149,18 @@ A pseudo example: root.text = 'modified content' Note that Python class methods return `None` by default when no `return` -statement is defined. Additionly all Python variables refer to objects by +statement is defined. Additionally all Python variables refer to objects by reference. Therefore, the above `run` method modifies the `root` element in place and returns `None`. The changes made to the `root` element and its children are retained. Some may be inclined to return the modified `root` element. While that would -work, it would cause a copy of the entire ElemetTree to be generated each -time the treeprocessor is run. Therefore, it is generally expected that +work, it would cause a copy of the entire ElementTree to be generated each +time the Treeprocessor is run. Therefore, it is generally expected that the `run` method would only return `None` or a new ElementTree object. For specifics on manipulating the ElementTree, see -[Working with the ElementTree][] below. +[Working with the ElementTree][workingwithetree] below. Postprocessors {: #postprocessors } ----------------------------------- @@ -168,8 +169,8 @@ Postprocessors manipulate the document after the ElementTree has been serialized into a string. Postprocessors should be used to work with the text just before output. -A Postprocessor should inherit from ``markdown.postprocessors.Postprocessor`` -and over-ride the ``run`` method which takes one argument ``text`` and returns +A Postprocessor should inherit from `markdown.postprocessors.Postprocessor` +and over-ride the `run` method which takes one argument `text` and returns a Unicode string. Postprocessors are run after the ElementTree has been serialized back into @@ -185,127 +186,128 @@ contents to a document: BlockParser {: #blockparser } ----------------------------- -Sometimes, pre/tree/postprocessors and Inline Patterns aren't going to do what -you need. Perhaps you want a new type of block type that needs to be integrated -into the core parsing. In such a situation, you can add/change/remove -functionality of the core ``BlockParser``. The BlockParser is composed of a -number of Blockproccessors. The BlockParser steps through each block of text -(split by blank lines) and passes each block to the appropriate Blockprocessor. -That Blockprocessor parses the block and adds it to the ElementTree. The +Sometimes, Preprocessors, Treeprocessors, Postprocessors, and Inline Patterns +are not going to do what you need. Perhaps you want a new type of block type +that needs to be integrated into the core parsing. In such a situation, you can +add/change/remove functionality of the core `BlockParser`. The BlockParser is +composed of a number of Blockprocessors. The BlockParser steps through each +block of text (split by blank lines) and passes each block to the appropriate +Blockprocessor. That Blockprocessor parses the block and adds it to the +ElementTree. The [Definition Lists][] extension would be a good example of an extension that adds/modifies Blockprocessors. -A Blockprocessor should inherit from ``markdown.blockprocessors.BlockProcessor`` -and implement both the ``test`` and ``run`` methods. +A Blockprocessor should inherit from `markdown.blockprocessors.BlockProcessor` +and implement both the `test` and `run` methods. -The ``test`` method is used by BlockParser to identify the type of block. -Therefore the ``test`` method must return a boolean value. If the test returns -``True``, then the BlockParser will call that Blockprocessor's ``run`` method. -If it returns ``False``, the BlockParser will move on to the next -BlockProcessor. +The `test` method is used by BlockParser to identify the type of block. +Therefore the `test` method must return a Boolean value. If the test returns +`True`, then the BlockParser will call that Blockprocessor's `run` method. +If it returns `False`, the BlockParser will move on to the next +Blockprocessor. -The **``test``** method takes two arguments: +The **`test`** method takes two arguments: -* **``parent``**: The parent etree Element of the block. This can be useful as - the block may need to be treated differently if it is inside a list, for +* **`parent`**: The parent ElementTree Element of the block. This can be useful + as the block may need to be treated differently if it is inside a list, for example. -* **``block``**: A string of the current block of text. The test may be a - simple string method (such as ``block.startswith(some_text)``) or a complex +* **`block`**: A string of the current block of text. The test may be a + simple string method (such as `block.startswith(some_text)`) or a complex regular expression. -The **``run``** method takes two arguments: +The **`run`** method takes two arguments: -* **``parent``**: A pointer to the parent etree Element of the block. The run +* **`parent`**: A pointer to the parent ElementTree Element of the block. The run method will most likely attach additional nodes to this parent. Note that - nothing is returned by the method. The Elementree object is altered in place. + nothing is returned by the method. The ElementTree object is altered in place. -* **``blocks``**: A list of all remaining blocks of the document. Your run +* **`blocks`**: A list of all remaining blocks of the document. Your run method must remove (pop) the first block from the list (which it altered in place - not returned) and parse that block. You may find that a block of text legitimately contains multiple block types. Therefore, after processing the first type, your processor can insert the remaining text into the beginning - of the ``blocks`` list for future parsing. + of the `blocks` list for future parsing. Please be aware that a single block can span multiple text blocks. For example, The official Markdown syntax rules state that a blank line does not end a Code Block. If the next block of text is also indented, then it is part of the previous block. Therefore, the BlockParser was specifically designed to -address these types of situations. If you notice the ``CodeBlockProcessor``, -in the core, you will note that it checks the last child of the ``parent``. -If the last child is a code block (``<pre><code>...</code></pre>``), then it +address these types of situations. If you notice the `CodeBlockProcessor`, +in the core, you will note that it checks the last child of the `parent`. +If the last child is a code block (`<pre><code>...</code></pre>`), then it appends that block to the previous code block rather than creating a new code block. -Each BlockProcessor has the following utility methods available: +Each Blockprocessor has the following utility methods available: -* **``lastChild(parent)``**: +* **`lastChild(parent)`**: - Returns the last child of the given etree Element or ``None`` if it had no - children. + Returns the last child of the given ElementTree Element or `None` if it + had no children. -* **``detab(text)``**: +* **`detab(text)`**: Removes one level of indent (four spaces by default) from the front of each line of the given text string. -* **``looseDetab(text, level)``**: +* **`looseDetab(text, level)`**: Removes "level" levels of indent (defaults to 1) from the front of each line of the given text string. However, this methods allows secondary lines to not be indented as does some parts of the Markdown syntax. -Each BlockProcessor also has a pointer to the containing BlockParser instance at -``self.parser``, which can be used to check or alter the state of the parser. -The BlockParser tracks it's state in a stack at ``parser.state``. The state -stack is an instance of the ``State`` class. +Each Blockprocessor also has a pointer to the containing BlockParser instance at +`self.parser`, which can be used to check or alter the state of the parser. +The BlockParser tracks it's state in a stack at `parser.state`. The state +stack is an instance of the `State` class. -**``State``** is a subclass of ``list`` and has the additional methods: +**`State`** is a subclass of `list` and has the additional methods: -* **``set(state)``**: +* **`set(state)`**: - Set a new state to string ``state``. The new state is appended to the end + Set a new state to string `state`. The new state is appended to the end of the stack. -* **``reset()``**: +* **`reset()`**: Step back one step in the stack. The last state at the end is removed from the stack. -* **``isstate(state)``**: +* **`isstate(state)`**: Test that the top (current) level of the stack is of the given string - ``state``. + `state`. -Note that to ensure that the state stack doesn't become corrupted, each time a +Note that to ensure that the state stack does not become corrupted, each time a state is set for a block, that state *must* be reset when the parser finishes parsing that block. -An instance of the **``BlockParser``** is found at ``Markdown.parser``. -``BlockParser`` has the following methods: +An instance of the **`BlockParser`** is found at `Markdown.parser`. +`BlockParser` has the following methods: -* **``parseDocument(lines)``**: +* **`parseDocument(lines)`**: Given a list of lines, an ElementTree object is returned. This should be - passed an entire document and is the only method the ``Markdown`` class + passed an entire document and is the only method the `Markdown` class calls directly. -* **``parseChunk(parent, text)``**: +* **`parseChunk(parent, text)`**: Parses a chunk of markdown text composed of multiple blocks and attaches - those blocks to the ``parent`` Element. The ``parent`` is altered in place + those blocks to the `parent` Element. The `parent` is altered in place and nothing is returned. Extensions would most likely use this method for block parsing. -* **``parseBlocks(parent, blocks)``**: +* **`parseBlocks(parent, blocks)`**: - Parses a list of blocks of text and attaches those blocks to the ``parent`` - Element. The ``parent`` is altered in place and nothing is returned. This + Parses a list of blocks of text and attaches those blocks to the `parent` + Element. The `parent` is altered in place and nothing is returned. This method will generally only be used internally to recursively parse nested blocks of text. While is is not recommended, an extension could subclass or completely replace -the ``BlockParser``. The new class would have to provide the same public API. +the `BlockParser`. The new class would have to provide the same public API. However, be aware that other extensions may expect the core parser provided and will not work with such a drastically different parser. @@ -313,34 +315,34 @@ Working with the ElementTree {: #working_with_et } -------------------------------------------------- As mentioned, the Markdown parser converts a source document to an -[ElementTree][] object before serializing that back to Unicode text. +[ElementTree][ElementTree] object before serializing that back to Unicode text. Markdown has provided some helpers to ease that manipulation within the context 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 +`markdown` rather than importing it directly. This will ensure you are using the same version of ElementTree as markdown. The module is found at -``markdown.util.etree`` within Markdown. +`markdown.util.etree` within Markdown. from markdown.util import etree -``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 +`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 (ElementTree). 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 -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``. +[Inline Patterns][]. In such a situation, simply insert the text as you normally +would and the text will be automatically run through the Inline Patterns. +However, if you do *not* want some text to be parsed by Inline Patterns, +then insert the text as an `AtomicString`. 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): +the second cell (`td2`) will be run through Inline Patterns latter): table = etree.Element("table") table.set("cellpadding", "2") # Set cellpadding to 2 @@ -352,7 +354,7 @@ the second cell (``td2``) will be run through InlinePatterns latter): table.tail = "Text after table" # Add text after table You can also manipulate an existing tree. Consider the following example which -adds a ``class`` attribute to ``<a>`` elements: +adds a `class` attribute to `<a>` elements: def set_link_class(self, element): for child in element: @@ -369,53 +371,53 @@ Integrating Your Code Into Markdown {: #integrating_into_markdown } 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 an ``Extension`` instance for each extension. Therefore, you -will need to define a class that extends ``markdown.extensions.Extension`` and -over-rides the ``extendMarkdown`` method. Within this class you will manage +Markdown accepts an `Extension` instance for each extension. Therefore, you +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 *then* try to deal with inline html, we will end up with a mess. +matters. For example, if we replace `http://...` links with `<a>` elements, +and *then* try to deal with inline HTML, we will end up with a mess. Therefore, the various types of processors and patterns are stored within an -instance of the Markdown class in [OrderedDict][]s. Your ``Extension`` class +instance of the Markdown class in [OrderedDict][]s. Your `Extension` class will need to manipulate those OrderedDicts appropriately. You may insert instances of your processors and patterns into the appropriate location in an OrderedDict, remove a built-in instance, or replace a built-in instance with your own. -### extendMarkdown {: #extendmarkdown } +### `extendMarkdown` {: #extendmarkdown } -The ``extendMarkdown`` method of a ``markdown.extensions.Extension`` class +The `extendMarkdown` method of a `markdown.extensions.Extension` class accepts two arguments: -* **``md``**: +* **`md`**: A pointer to the instance of the Markdown class. You should use this to access the [OrderedDict][]s of processors and patterns. They are found under the following attributes: - * ``md.preprocessors`` - * ``md.inlinePatterns`` - * ``md.parser.blockprocessors`` - * ``md.treeprocessors`` - * ``md.postprocessors`` + * `md.preprocessors` + * `md.inlinePatterns` + * `md.parser.blockprocessors` + * `md.treeprocessors` + * `md.postprocessors` Some other things you may want to access in the markdown instance are: - * ``md.htmlStash`` - * ``md.output_formats`` - * ``md.set_output_format()`` - * ``md.output_format`` - * ``md.serializer`` - * ``md.registerExtension()`` - * ``md.html_replacement_text`` - * ``md.tab_length`` - * ``md.enable_attributes`` - * ``md.smart_emphasis`` + * `md.htmlStash` + * `md.output_formats` + * `md.set_output_format()` + * `md.output_format` + * `md.serializer` + * `md.registerExtension()` + * `md.html_replacement_text` + * `md.tab_length` + * `md.enable_attributes` + * `md.smart_emphasis` -* **``md_globals``**: +* **`md_globals`**: Contains all the various global variables within the markdown module. @@ -447,32 +449,32 @@ in a specific location in relation to the existing items. Think of OrderedDict as a combination of a list and a dictionary as it has methods common to both. For example, you can get and set items using the -``od[key] = value`` syntax and the methods ``keys()``, ``values()``, and -``items()`` work as expected with the keys, values and items returned in the -proper order. At the same time, you can use ``insert()``, ``append()``, and -``index()`` as you would with a list. +`od[key] = value` syntax and the methods `keys()`, `values()`, and +`items()` work as expected with the keys, values and items returned in the +proper order. At the same time, you can use `insert()`, `append()`, and +`index()` as you would with a list. Generally speaking, within Markdown extensions you will be using the special -helper method ``add()`` to add additional items to an existing OrderedDict. +helper method `add()` to add additional items to an existing OrderedDict. -The ``add()`` method accepts three arguments: +The `add()` method accepts three arguments: -* **``key``**: A string. The key is used for later reference to the item. +* **`key`**: A string. The key is used for later reference to the item. -* **``value``**: The object instance stored in this item. +* **`value`**: The object instance stored in this item. -* **``location``**: Optional. The items location in relation to other items. +* **`location`**: Optional. The items location in relation to other items. Note that the location can consist of a few different values: - * The special strings ``"_begin"`` and ``"_end"`` insert that item at the + * The special strings `"_begin"` and `"_end"` insert that item at the beginning or end of the OrderedDict respectively. - * A less-than sign (``<``) followed by an existing key (i.e.: - ``"<somekey"``) inserts that item before the existing key. + * A less-than sign (`<`) followed by an existing key (i.e.: + `"<somekey"`) inserts that item before the existing key. - * A greater-than sign (``>``) followed by an existing key (i.e.: - ``">somekey"``) inserts that item after the existing key. + * A greater-than sign (`>`) followed by an existing key (i.e.: + `">somekey"`) inserts that item after the existing key. Consider the following example: @@ -485,8 +487,8 @@ Consider the following example: [("one", 1), ("three", 3), ("four", 4)] Note that when building an OrderedDict in order, the extra features of the -``add`` method offer no real value and are not necessary. However, when -manipulating an existing OrderedDict, ``add`` can be very helpful. So let's +`add` method offer no real value and are not necessary. However, when +manipulating an existing OrderedDict, `add` can be very helpful. So let's insert another item into the OrderedDict. >>> od.add('two', 2, '>one') # Insert after 'one' @@ -495,16 +497,16 @@ insert another item into the OrderedDict. Now let's insert another item. - >>> od.add('twohalf', 2.5, '<three') # Insert before 'three' + >>> od.add('two-point-five', 2.5, '<three') # Insert before 'three' >>> od.keys() - ["one", "two", "twohalf", "three", "four"] + ["one", "two", "two-point-five", "three", "four"] -Note that we also could have set the location of "twohalf" to be 'after two' -(i.e.: ``'>two'``). However, it's unlikely that you will have control over the +Note that we also could have set the location of "two-point-five" to be 'after two' +(i.e.: `'>two'`). However, it's unlikely that you will have control over the order in which extensions will be loaded, and this could affect the final -sorted order of an OrderedDict. For example, suppose an extension adding -'twohalf' in the above examples was loaded before a separate extension which -adds 'two'. You may need to take this into consideration when adding your +sorted order of an OrderedDict. For example, suppose an extension adding +"two-point-five" in the above examples was loaded before a separate extension +which adds 'two'. You may need to take this into consideration when adding your extension components to the various markdown OrderedDicts. Once an OrderedDict is created, the items are available via key: @@ -534,32 +536,32 @@ extension: md.reset() html2 = md.convert(text_without_footnote) -Without calling ``reset``, the footnote definitions from the first document will +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 +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: +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`` +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 +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. +`reset` method. -### Config Settings {: #configsettings } +### Configuration Settings {: #configsettings } If an extension uses any parameters that the user may want to change, -those parameters should be stored in ``self.config`` of your -``markdown.extensions.Extension`` class in the following format: +those parameters should be stored in `self.config` of your +`markdown.extensions.Extension` class in the following format: class MyExtension(markdown.extensions.Extension): def __init__(self, **kwargs): @@ -567,7 +569,7 @@ those parameters should be stored in ``self.config`` of your 'option2' : ['value2', 'description2'] } super(MyExtension, self).__init__(**kwargs) -When implemented this way the config parameters can be over-ridden at +When implemented this way the configuration parameters can be over-ridden at run time (thus the call to `super`). For example: markdown.Markdown(extensions=[MyExtension(option1='other value']) @@ -576,38 +578,38 @@ Note that if a keyword is passed in that is not already defined in `self.config`, then a `KeyError` is raised. The `markdown.extensions.Extension` class and its subclasses have the -following methods available to assist in working with config settings: +following methods available to assist in working with configuration settings: -* **``getConfig(key [, default])``**: +* **`getConfig(key [, default])`**: Returns the stored value for the given `key` or `default` if the `key` does not exist. If not set, `default` returns an empty string. -* **``getConfigs()``**: +* **`getConfigs()`**: Returns a dict of all key/value pairs. -* **``getConfigInfo()``**: +* **`getConfigInfo()`**: - Returns all config descriptions as a list of tuples. + Returns all configuration descriptions as a list of tuples. -* **``setConfig(key, value)``**: +* **`setConfig(key, value)`**: - Sets a config setting for `key` with the given `value`. If `key` is + Sets a configuration setting for `key` with the given `value`. If `key` is unknown, a `KeyError` is raised. If the previous value of `key` was - a boolean value, then `value` is converted to a boolean value. If + a Boolean value, then `value` is converted to a Boolean value. If the previous value of `key` is `None`, then `value` is converted to - a boolean value except when it is `None`. No conversion takes place + a Boolean value except when it is `None`. No conversion takes place when the previous value of `key` is a string. -* **``setConfigs(items)``**: +* **`setConfigs(items)`**: - Sets multiple config settings given a dict of key/value pairs. + Sets multiple configuration settings given a dict of key/value pairs. -### makeExtension {: #makeextension } +### `makeExtension` {: #makeextension } As noted in the [library reference] an instance of an extension can be passed -directly to Markdown. In fact, this is the prefered way to use third-party +directly to Markdown. In fact, this is the preferred way to use third-party extensions. For example: @@ -617,7 +619,7 @@ For example: myext = myextension.MyExtension(option='value') md = markdown.Markdown(extensions=[myext]) -Markdown also accepts "named" third party extensions for those occassions +Markdown also accepts "named" third party extensions for those occasions when it is impractical to import an extension directly (from the command line or from within templates). @@ -627,7 +629,7 @@ to your users and would like to include a custom markdown extension within your library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py` contains the extension and the `mylib` directory is on the PYTHONPATH. -The string can also include the name of the class seperated by a colon. +The string can also include the name of the class separated by a colon. Therefore, if you were to import the class like this: from path.to.module import SomeExtensionClass @@ -636,8 +638,8 @@ Then the named extension would comprise this string: "path.to.module:SomeExtensionClass" -You do not need to do anything special to support this feature. As long as your extension -class is able to be imported, a user can include it with the above syntax. +You do not need to do anything special to support this feature. As long as your +extension class is able to be imported, a user can include it with the above syntax. The above two methods are especially useful if you need to implement a large number of extensions with more than one residing in a module. However, if you do not want to require @@ -658,11 +660,11 @@ the module and call the `makeExtension` function to initiate your extension. [Preprocessors]: #preprocessors -[InlinePatterns]: #inlinepatterns +[Inline Patterns]: #inlinepatterns [Treeprocessors]: #treeprocessors [Postprocessors]: #postprocessors [BlockParser]: #blockparser -[Working with the ElementTree]: #working_with_et +[workingwithetree]: #working_with_et [Integrating your code into Markdown]: #integrating_into_markdown [extendMarkdown]: #extendmarkdown [OrderedDict]: #ordereddict diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt index 01329c6..1951347 100644 --- a/docs/extensions/attr_list.txt +++ b/docs/extensions/attr_list.txt @@ -71,7 +71,7 @@ The above results in the following output: ### Inline ### To define attributes on inline elements, the attribute list should be defined -immediately after the inline element with no whitespace. +immediately after the inline element with no white space. [link](http://example.com){: class="foo bar" title="Some title!" } diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 92f8c12..5e802b8 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -25,23 +25,23 @@ You will also need to [download][dl] and install the Pygments package on your appropriate rules for them, which are either defined in or linked from the header of your HTML templates. See the excellent [documentation][] for more details. If no language is defined, Pygments will attempt to guess the -language. When that fails, the code block will display as un-highlighted code. +language. When that fails, the code block will not be highlighted. [dl]: http://pygments.org/download/ [documentation]: http://pygments.org/docs !!! Note - The css and/or JavaScript is not included as part of this extension + The CSS and/or JavaScript is not included as part of this extension but must be provided by the end user. The Pygments project provides - default css styles which you may find to be a useful starting point. + default CSS styles which you may find to be a useful starting point. Syntax ------ The CodeHilite extension follows the same [syntax][] as regular Markdown code -blocks, with one exception. The hiliter needs to know what language to use for -the code block. There are three ways to tell the hiliter what language the code -block contains and each one has a different result. +blocks, with one exception. The highlighter needs to know what language to use for +the code block. There are three ways to tell the highlighter what language the +code block contains and each one has a different result. !!! Note The format of the language identifier only effects the display of line numbers @@ -52,9 +52,9 @@ block contains and each one has a different result. [syntax]: http://daringfireball.net/projects/markdown/syntax#precode -### SheBang (with path) ### +### Shebang (with path) ### -If the first line of the codeblock contains a shebang, the language is derived +If the first line of the code block contains a shebang, the language is derived from that and line numbers are used. #!/usr/bin/python @@ -65,7 +65,7 @@ Will result in: #!/usr/bin/python # Code goes here ... -### SheBang (no path) ### +### Shebang (no path) ### If the first line contains a shebang, but the shebang line does not contain a path (a single `/` or even a space), then that line is removed from the code @@ -92,7 +92,7 @@ Will result in: # Code goes here ... Certain lines can be selected for emphasis with the colon syntax. When -using Pygments' default css styles, emphasized lines have a yellow background. +using Pygments' default CSS styles, emphasized lines have a yellow background. This is useful to direct the reader's attention to specific lines. :::python hl_lines="1 3" @@ -143,7 +143,7 @@ The following options are provided to configure the output: Using `True` will force every code block to have line numbers, even when using colons (`:::`) for language identification. - Using `False` will turn off all line numbers, even when using SheBangs + Using `False` will turn off all line numbers, even when using shebangs (`#!`) for language identification. * **`guess_lang`**: @@ -157,7 +157,7 @@ The following options are provided to configure the output: `codehilite`. * **`pygments_style`**: - Pygments HTML Formatter Style (ColorScheme). Defaults to `default`. + Pygments HTML Formatter Style (`ColorScheme`). Defaults to `default`. !!! Note This is useful only when `noclasses` is set to `True`, otherwise the diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt index bf4d12f..5347d81 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.txt @@ -1,7 +1,7 @@ title: Extra Extension prev_title: Extensions prev_url: index.html -next_title: Abreviations Extension +next_title: Abbreviations Extension next_url: abbreviations.html Python-Markdown Extra @@ -45,11 +45,19 @@ your own clone of Extra under a different name Markdown Inside HTML Blocks --------------------------- -Unlike the other Extra features, this feature is built into the markdown core and is turned on when `markdown.extensions.extra` is enabled. +Unlike the other Extra features, this feature is built into the markdown core and +is turned on when `markdown.extensions.extra` is enabled. -The content of any raw html block element can be Markdown-formatted simply by adding a `markdown` attribute to the opening tag. The markdown attribute will be stripped from the output, but all other attributes will be preserved. +The content of any raw HTML block element can be Markdown-formatted simply by +adding a `markdown` attribute to the opening tag. The markdown attribute will be +stripped from the output, but all other attributes will be preserved. -If the markdown value is set to `1` (recommended) or any value other than `span` or `block`, the default behavior will be executed: `p`,`h[1-6]`,`li`,`dd`,`dt`,`td`,`th`,`legend`, and `address` elements skip block parsing while others do not. If the default is overrident by a value of `span`, *block parsing will be skipped* regardless of tag. If the default is overriden by a value of `block`, *block parsing will occur* regardless of tag. +If the markdown value is set to `1` (recommended) or any value other than `span` +or `block`, the default behavior will be executed: `p`,`h[1-6]`,`li`,`dd`,`dt`, +`td`,`th`,`legend`, and `address` elements skip block parsing while others do not. +If the default is overridden by a value of `span`, *block parsing will be skipped* +regardless of tag. If the default is overridden by a value of `block`, +*block parsing will occur* regardless of tag. #### Simple Example: ``` @@ -67,8 +75,9 @@ This is *true* markdown text. </div> ``` -### Nested Markdown Inside HTML BLocks -Nested elements are more sensitive and must be used cautiously. To avoid unexpected results: +### Nested Markdown Inside HTML Blocks +Nested elements are more sensitive and must be used cautiously. To avoid +unexpected results: * Only nest elements within block mode elements. * Follow the closing tag of inner elements with a blank line. @@ -104,12 +113,12 @@ This `p` block *is* foolishly wrapped in further paragraph tags. The tail of the `BlockModeOverride` subelement. <div name="RawHtml"> -Raw html blocks may also be nested. +Raw HTML blocks may also be nested. </div> </div> -This text is after the markdown in html. +This text is after the markdown in HTML. ``` #### Result: ``` @@ -130,9 +139,9 @@ Note: Subelements are not required to have tail text.</div> </p> <p>The tail of the <code>BlockModeOverride</code> subelement.</p> <div name="RawHtml"> -Raw html blocks may also be nested. +Raw HTML blocks may also be nested. </div> </div> -<p>This text is after the markdown in html.</p> +<p>This text is after the markdown in HTML.</p> ``` diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.txt index 19999fd..982f5d4 100644 --- a/docs/extensions/fenced_code_blocks.txt +++ b/docs/extensions/fenced_code_blocks.txt @@ -45,7 +45,7 @@ part of the list. In addition to PHP Extra's syntax, you can define the language of the code block for use by syntax highlighters etc. The language will be assigned as a class attribute of the ``<code>`` element in the output. Therefore, you should -define the language as you would a css class - ``.language``. For consistency +define the language as you would a CSS class - ``.language``. For consistency with other markdown syntax, the language can *optionally* be wrapped in curly brackets: @@ -65,13 +65,13 @@ The above will output: <pre><code class="html"><p>HTML Document</p> </code></pre> -[Github][]'s backtick (`\``) syntax is also supported: +[GitHub][]'s backtick (`\``) syntax is also supported: ```python # more python code ``` -[Github]: http://github.github.com/github-flavored-markdown/ +[GitHub]: http://github.github.com/github-flavored-markdown/ ### Emphasized Lines ### diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt index 40081e5..e9b0451 100644 --- a/docs/extensions/footnotes.txt +++ b/docs/extensions/footnotes.txt @@ -38,7 +38,7 @@ caret has any special meaning. A footnote content must start with the label followed by a colon and at least one space. The label used to define the content must exactly match the label used -in the body (including capitalization and whitespace). The content would then +in the body (including capitalization and white space). The content would then follow the label either on the same line or on the next line. The content may contain multiple lines, paragraphs, code blocks, blockquotes and most any other markdown syntax. The additional lines must be indented one level (four spaces or diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.txt index 42e640e..5557b1b 100644 --- a/docs/extensions/header_id.txt +++ b/docs/extensions/header_id.txt @@ -55,14 +55,14 @@ The following options are provided to configure the output: Default: `1` The `level` setting allows you to automatically adjust the header levels to - fit within the hierarchy of your html templates. For example, suppose the + fit within the hierarchy of your HTML templates. For example, suppose the markdown text for a page should not contain any headers higher than level 3 (`<h3>`). The following will accomplish that: >>> text = ''' ... #Some Header ... ## Next Level''' - >>> from markdown.extensions.headerid import HeaderIdExtension + >>> from markdown.extensions.headerid import HeaderIdExtension >>> html = markdown.markdown(text, extensions=[HeaderIdExtension(level=3)]) >>> print html <h3 id="some_header">Some Header</h3> @@ -79,13 +79,14 @@ The following options are provided to configure the output: >>> text = ''' ... # Some Header ... # Header with ID # { #foo }''' - >>> html = markdown.markdown(text, - extensions=['attr_list', HeaderIdExtension(forceid=False)]) + >>> html = markdown.markdown(text, + extensions=['markdown.extensions.attr_list', + HeaderIdExtension(forceid=False)]) >>> print html <h1>Some Header</h1> <h1 id="foo">Header with ID</h1> -* **`separator`**: Word separator. Character which replaces whitespace in id. +* **`separator`**: Word separator. Character which replaces white space in id. Default: `-` diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.txt index 517d3e6..3057bfa 100644 --- a/docs/extensions/meta_data.txt +++ b/docs/extensions/meta_data.txt @@ -49,7 +49,7 @@ line of a document must not be blank. Alternatively, if the first line in the document is `---`, a YAML document separator, then the meta-data is searched for between it and the next `---` -(or `...`) line. Even though YAML delimitors are supported, meta-data is +(or `...`) line. Even though YAML deliminators are supported, meta-data is not parsed as YAML unless the `yaml` option is set (see below). All meta-data is stripped from the document prior to any further processing @@ -69,7 +69,7 @@ The following options are provided to configure the output: If `yaml` is set to `True`, the lines between `---` separators are parsed as a full YAML object. PyYAML is required for this, and a warning is - issued if PyYAML (or equivalent) isn't available. + issued if PyYAML (or equivalent) is not available. Accessing the Meta-Data ----------------------- @@ -102,7 +102,7 @@ assumptions are made regarding the data. It is simply passed as found to the Note, if `yaml` option is set, the resulting `Meta` attribute is the object as returned by `yaml.load()` and may deviate significantly from the above -description (e.g. may be a list of dicts, with value objects other than +description (e.g. may be a list of dictionaries, with value objects other than strings, ...). Perhaps the meta-data could be passed into a template system, or used by diff --git a/docs/extensions/nl2br.txt b/docs/extensions/nl2br.txt index 1196615..8ba27c8 100644 --- a/docs/extensions/nl2br.txt +++ b/docs/extensions/nl2br.txt @@ -4,13 +4,13 @@ prev_url: meta_data.html next_title: Sane Lists Extension next_url: sane_lists.html -NL2BR -===== +New-Line-to-Break Extension +=========================== Summary ------- -The NL2BR extension will cause newlines to be treated as hard breaks; like +The New-Line-to-Break (`nl2b`) Extension will cause newlines to be treated as hard breaks; like StackOverflow and [GitHub][] flavored Markdown do. [Github]: http://github.github.com/github-flavored-markdown/ diff --git a/docs/extensions/smarty.txt b/docs/extensions/smarty.txt index a0680af..d511da1 100644 --- a/docs/extensions/smarty.txt +++ b/docs/extensions/smarty.txt @@ -26,7 +26,7 @@ Using the configuration option 'substitutions' you can overwrite the default substitutions. Just pass a dict mapping (a subset of) the keys to the substitution strings. -For example, one might use the following config to get correct quotes for +For example, one might use the following configuration to get correct quotes for the German language: extensionConfigs = { @@ -41,8 +41,8 @@ the German language: } !!! note - This extension reimplements the Python [SmartyPants] - library by intregated it into the markdown parser. + This extension re-implements the Python [SmartyPants] + library by integrating it into the markdown parser. While this does not provide any additional features, it does offer a few advantages. Notably, it will not try to work on highlighted code blocks (using the diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt index 0705564..2cd1fa1 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.txt @@ -88,7 +88,7 @@ The following options are provided to configure the output: * **`permalink`**: Set to `True` or a string to generate permanent links at the end of each header. - Useful with Sphinx stylesheets. + Useful with Sphinx style sheets. When set to `True` the paragraph symbol (¶ or "`¶`") is used as the link text. When set to a string, the provided string is used as the link text. @@ -97,7 +97,7 @@ The following options are provided to configure the output: Base level for headers. Defaults to `1`. The `baselevel` setting allows the header levels to be automatically adjusted to - fit within the hierarchy of your html templates. For example, suppose the + fit within the hierarchy of your HTML templates. For example, suppose the Markdown text for a page should not contain any headers higher than level 3 (`<h3>`). The following will accomplish that: @@ -124,4 +124,4 @@ The following options are provided to configure the output: The callable must return a string appropriate for use in HTML `id` attributes. * **`separator`**: - Word separator. Character which replaces whitespace in id. Defaults to "`-`".
\ No newline at end of file + Word separator. Character which replaces white space in id. Defaults to "`-`".
\ No newline at end of file diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt index b52e0d0..948b957 100644 --- a/docs/extensions/wikilinks.txt +++ b/docs/extensions/wikilinks.txt @@ -25,12 +25,12 @@ number, dashes, underscores and spaces surrounded by double brackets. Therefore [[Bracketed]] -would produce the following html: +would produce the following HTML: <a href="/Bracketed/" class="wikilink">Bracketed</a> -Note that wikilinks are automatically assigned `class="wikilink"` making it -easy to style wikilinks differently from other links on a page if one so +Note that WikiLinks are automatically assigned `class="wikilink"` making it +easy to style WikiLinks differently from other links on a page if one so desires. See below for ways to alter the class. Also note that when a space is used, the space is converted to an underscore in @@ -54,7 +54,7 @@ configuring extensions. The default behavior is to point each link to the document root of the current domain and close with a trailing slash. Additionally, each link is assigned to -the html class `wikilink`. +the HTML class `wikilink`. The following options are provided to change the default behavior: @@ -74,7 +74,7 @@ The following options are provided to change the default behavior: ### Examples ### -For an example, let us suppose links should always point to the subdirectory +For an example, let us suppose links should always point to the sub-directory `/wiki/` and end with `.html` >>> from markdown.extensions.wikilinks import WikiLinkExtension @@ -104,7 +104,7 @@ The option is also provided to change or remove the class attribute. ... extensions=[WikiLinkExtension(html_class='myclass')] ... ) -Would cause all wikilinks to be assigned to the class `myclass`. +Would cause all WikiLinks to be assigned to the class `myclass`. <a href="/WikiLink/" class="myclass">WikiLink</a> |