diff options
Diffstat (limited to 'docs/extensions')
| -rw-r--r-- | docs/extensions/abbreviations.md | 45 | ||||
| -rw-r--r-- | docs/extensions/abbreviations.txt | 45 | ||||
| -rw-r--r-- | docs/extensions/admonition.md (renamed from docs/extensions/admonition.txt) | 61 | ||||
| -rw-r--r-- | docs/extensions/api.md (renamed from docs/extensions/api.txt) | 596 | ||||
| -rw-r--r-- | docs/extensions/attr_list.md (renamed from docs/extensions/attr_list.txt) | 76 | ||||
| -rw-r--r-- | docs/extensions/code_hilite.md (renamed from docs/extensions/code_hilite.txt) | 76 | ||||
| -rw-r--r-- | docs/extensions/definition_lists.md | 52 | ||||
| -rw-r--r-- | docs/extensions/definition_lists.txt | 53 | ||||
| -rw-r--r-- | docs/extensions/extra.md (renamed from docs/extensions/extra.txt) | 71 | ||||
| -rw-r--r-- | docs/extensions/fenced_code_blocks.md (renamed from docs/extensions/fenced_code_blocks.txt) | 108 | ||||
| -rw-r--r-- | docs/extensions/footnotes.md (renamed from docs/extensions/footnotes.txt) | 63 | ||||
| -rw-r--r-- | docs/extensions/header_id.md (renamed from docs/extensions/header_id.txt) | 65 | ||||
| -rw-r--r-- | docs/extensions/index.md (renamed from docs/extensions/index.txt) | 57 | ||||
| -rw-r--r-- | docs/extensions/meta_data.md (renamed from docs/extensions/meta_data.txt) | 89 | ||||
| -rw-r--r-- | docs/extensions/nl2br.md | 35 | ||||
| -rw-r--r-- | docs/extensions/nl2br.txt | 37 | ||||
| -rw-r--r-- | docs/extensions/sane_lists.md (renamed from docs/extensions/sane_lists.txt) | 64 | ||||
| -rw-r--r-- | docs/extensions/smart_strong.md | 39 | ||||
| -rw-r--r-- | docs/extensions/smart_strong.txt | 41 | ||||
| -rw-r--r-- | docs/extensions/smarty.md (renamed from docs/extensions/smarty.txt) | 42 | ||||
| -rw-r--r-- | docs/extensions/tables.md | 58 | ||||
| -rw-r--r-- | docs/extensions/tables.txt | 58 | ||||
| -rw-r--r-- | docs/extensions/toc.md (renamed from docs/extensions/toc.txt) | 97 | ||||
| -rw-r--r-- | docs/extensions/wikilinks.md (renamed from docs/extensions/wikilinks.txt) | 103 |
24 files changed, 1060 insertions, 971 deletions
diff --git a/docs/extensions/abbreviations.md b/docs/extensions/abbreviations.md new file mode 100644 index 0000000..d580d56 --- /dev/null +++ b/docs/extensions/abbreviations.md @@ -0,0 +1,45 @@ +title: Abbreviations Extension + +Abbreviations +============= + +Summary +------- + +The Abbreviations extension adds the ability to define abbreviations. +Specifically, any defined abbreviation is wrapped in an `<abbr>` tag. + +The Abbreviations extension is included in the standard Markdown library. + +Syntax +------ + +Abbreviations are defined using the syntax established in +[PHP Markdown Extra][php]. + +[php]: http://www.michelf.com/projects/php-markdown/extra/#abbr + +Thus, the following text (taken from the above referenced PHP documentation): + +```md +The HTML specification +is maintained by the W3C. + +*[HTML]: Hyper Text Markup Language +*[W3C]: World Wide Web Consortium +``` + +will be rendered as: + +```html +<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification +is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p> +``` + +Usage +----- + +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.abbr` +as the name of the extension. + +This extension does not accept any special configuration options. diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.txt deleted file mode 100644 index 9ac7c95..0000000 --- a/docs/extensions/abbreviations.txt +++ /dev/null @@ -1,45 +0,0 @@ -title: Abbreviations Extension -prev_title: Extra Extension -prev_url: extra.html -next_title: Attribute Lists Extension -next_url: attr_list.html - -Abbreviations -============= - -Summary -------- - -The Abbreviations extension adds the ability to define abbreviations. -Specifically, any defined abbreviation is wrapped in an `<abbr>` tag. - -The Abbreviations extension is included in the standard Markdown library. - -Syntax ------- - -Abbreviations are defined using the syntax established in -[PHP Markdown Extra][php]. - -[php]: http://www.michelf.com/projects/php-markdown/extra/#abbr - -Thus, the following text (taken from the above referenced PHP documentation): - - The HTML specification - is maintained by the W3C. - - *[HTML]: Hyper Text Markup Language - *[W3C]: World Wide Web Consortium - -will be rendered as: - - <p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification - is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p> - -Usage ------ - -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.abbr` -as the name of the extension. - -This extension does not accept any special configuration options. diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.md index d68bd5d..26e6299 100644 --- a/docs/extensions/admonition.txt +++ b/docs/extensions/admonition.md @@ -1,8 +1,4 @@ -title: Admonition Extension -prev_title: Smart Strong Extension -prev_url: smart_strong.html -next_title: CodeHilite Extension -next_url: code_hilite.html +title: Admonition Extension Admonition ========== @@ -21,47 +17,60 @@ Syntax Admonitions are created using the following syntax: - !!! type "optional explicit title within double quotes" - Any number of other indented markdown elements. +```md +!!! type "optional explicit title within double quotes" + Any number of other indented markdown elements. - This is the second paragraph. + This is the second paragraph. +``` `type` will be used as the CSS class name and as default title. It must be a single word. So, for instance: - !!! note - You should note that the title will be automatically capitalized. +```md +!!! note + You should note that the title will be automatically capitalized. +``` will render: - <div class="admonition note"> - <p class="admonition-title">Note</p> - <p>You should note that the title will be automatically capitalized.</p> - </div> +```html +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>You should note that the title will be automatically capitalized.</p> +</div> +``` Optionally, you can use custom titles. For instance: - !!! danger "Don't try this at home" - ... +```md +!!! danger "Don't try this at home" + ... +``` will render: - <div class="admonition danger"> - <p class="admonition-title">Don't try this at home</p> - <p>...</p> - </div> +```html +<div class="admonition danger"> +<p class="admonition-title">Don't try this at home</p> +<p>...</p> +</div> +``` If you don't want a title, use a blank string `""`: - !!! important "" - This is a admonition box without a title. +```md +!!! important "" + This is a admonition box without a title. +``` results in: - <div class="admonition important"> - <p>This is a admonition box without a title.</p> - </div> - +```html +<div class="admonition important"> +<p>This is a admonition box without a title.</p> +</div> +``` rST suggests the following `types`, but you're free to use whatever you want: attention, caution, danger, error, hint, important, note, tip, warning. diff --git a/docs/extensions/api.txt b/docs/extensions/api.md index 246bb27..3d8cfff 100644 --- a/docs/extensions/api.txt +++ b/docs/extensions/api.md @@ -1,117 +1,116 @@ title: Extensions API -prev_title: WikiLinks Extension -prev_url: wikilinks.html -next_title: Test Suite -next_url: ../test_suite.html -Writing Extensions for Python-Markdown -====================================== +# Writing Extensions for Python-Markdown -Python-Markdown includes an API for extension writers to plug their own +Python-Markdown includes an API for extension writers to plug their own 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, +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 -output of the parser before it is returned. If you really want to dive in, +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. -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 -helpful. For example, the [Footnotes][] extension uses most of the features +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 +helpful. For example, the [Footnotes][] extension uses most of the features documented here. -Preprocessors {: #preprocessors } ---------------------------------- +## Preprocessors {: #preprocessors } -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 +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 -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 +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 return either that list, or an altered list of Unicode strings. A pseudo example: - from markdown.preprocessors import Preprocessor - - class MyPreprocessor(Preprocessor): - def run(self, lines): - new_lines = [] - for line in lines: - m = MYREGEX.match(line) - if m: - # do stuff - else: - new_lines.append(line) - return new_lines - -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 -one of its children. Each pattern object uses a single regular expression and +```python +from markdown.preprocessors import Preprocessor + +class MyPreprocessor(Preprocessor): + def run(self, lines): + new_lines = [] + for line in lines: + m = MYREGEX.match(line) + if m: + # do stuff + else: + new_lines.append(line) + return new_lines +``` + +## 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 +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 + Accepts a match object and returns an ElementTree element of a plain Unicode string. -Also, Inline Patterns can define the property `ANCESTOR_EXCLUDES` with either -a list or tuple of undesirable ancestors. The pattern should not match if it +Also, Inline Patterns can define the property `ANCESTOR_EXCLUDES` with either +a list or tuple of undesirable ancestors. The pattern should not match if it would cause the content to be a descendant of one of the defined tag names. 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 +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 pattern. For an example, consider this simplified emphasis pattern: - from markdown.inlinepatterns import Pattern - from markdown.util import etree +```python +from markdown.inlinepatterns import Pattern +from markdown.util import etree - class EmphasisPattern(Pattern): - def handleMatch(self, m): - el = etree.Element('em') - el.text = m.group(3) - return el +class EmphasisPattern(Pattern): + def handleMatch(self, m): + el = etree.Element('em') + el.text = m.group(3) + return el +``` As discussed in [Integrating Your Code Into Markdown][], an instance of this class will need to be provided to Markdown. That instance would be created like so: - # an oversimplified regex - MYPATTERN = r'\*([^*]+)\*' - # pass in pattern and create instance - emphasis = EmphasisPattern(MYPATTERN) +```python +# an oversimplified regex +MYPATTERN = r'\*([^*]+)\*' +# pass in pattern and create instance +emphasis = EmphasisPattern(MYPATTERN) +``` Actually it would not be necessary to create that pattern (and not just because a more sophisticated emphasis pattern already exists in Markdown). The fact is, 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 +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`. -**Generic Pattern Classes** +### Generic Pattern Classes * **`SimpleTextPattern(pattern)`**: @@ -127,12 +126,11 @@ Feel free to use or extend any of the Pattern classes found at 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 +or use as well. Read through the source and see if there is anything you can use. You might even get a few ideas for different approaches to your specific situation. -Treeprocessors {: #treeprocessors } ------------------------------------ +## Treeprocessors {: #treeprocessors } Treeprocessors manipulate an ElementTree object after it has passed through the core BlockParser. This is where additional manipulation of the tree takes @@ -140,22 +138,24 @@ place. Additionally, the InlineProcessor is a Treeprocessor which steps through 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 ElementTree -object) and either modifies that root element and returns `None` or returns a +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. A pseudo example: - from markdown.treeprocessors import Treeprocessor +```python +from markdown.treeprocessors import Treeprocessor - class MyTreeprocessor(Treeprocessor): - def run(self, root): - root.text = 'modified content' +class MyTreeprocessor(Treeprocessor): + def run(self, root): + root.text = 'modified content' +``` -Note that Python class methods return `None` by default when no `return` +Note that Python class methods return `None` by default when no `return` 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 +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 @@ -163,32 +163,32 @@ 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 +For specifics on manipulating the ElementTree, see [Working with the ElementTree][workingwithetree] below. -Postprocessors {: #postprocessors } ------------------------------------ +## Postprocessors {: #postprocessors } -Postprocessors manipulate the document after the ElementTree has been +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 -Unicode text. For example, this may be an appropriate place to add a table of +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: - from markdown.postprocessors import Postprocessor +```python +from markdown.postprocessors import Postprocessor - class TocPostprocessor(Postprocessor): - def run(self, text): - return MYMARKERRE.sub(MyToc, text) +class TocPostprocessor(Postprocessor): + def run(self, text): + return MYMARKERRE.sub(MyToc, text) +``` -BlockParser {: #blockparser } ------------------------------ +## BlockParser {: #blockparser } Sometimes, Preprocessors, Treeprocessors, Postprocessors, and Inline Patterns are not going to do what you need. Perhaps you want a new type of block type @@ -207,7 +207,7 @@ 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 +If it returns `False`, the BlockParser will move on to the next Blockprocessor. The **`test`** method takes two arguments: @@ -216,49 +216,49 @@ The **`test`** method takes two arguments: 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: -* **`parent`**: A pointer to the parent ElementTree 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 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 + 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. 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 +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 -appends that block to the previous code block rather than creating a new +appends that block to the previous code block rather than creating a new code block. Each Blockprocessor has the following utility methods available: -* **`lastChild(parent)`**: +* **`lastChild(parent)`**: 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 + 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 @@ -268,19 +268,19 @@ stack is an instance of the `State` class. **`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 + 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 + Test that the top (current) level of the stack is of the given string `state`. Note that to ensure that the state stack does not become corrupted, each time a @@ -290,24 +290,24 @@ parsing that block. 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 + 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 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 - and nothing is returned. Extensions would most likely use this method for + Parses a chunk of markdown text composed of multiple blocks and attaches + 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 - method will generally only be used internally to recursively parse nested + 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 @@ -315,91 +315,97 @@ 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. -Working with the ElementTree {: #working_with_et } --------------------------------------------------- +## Working with the ElementTree {: #working_with_et } -As mentioned, the Markdown parser converts a source document to an -[ElementTree][ElementTree] object before serializing that back to Unicode text. -Markdown has provided some helpers to ease that manipulation within the context +As mentioned, the Markdown parser converts a source document to an +[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 -the same version of ElementTree as markdown. The module is found at +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 found at `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 (ElementTree). In each instance, `cElementTree` is -tried first, then ElementTree if the faster C implementation is not +```python +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 (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 +Sometimes you may want text inserted into an element to be parsed by [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. +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) +```python +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 +Here's a basic example which creates an HTML table (note that the contents of the second cell (`td2`) will be run through Inline Patterns latter): - table = etree.Element("table") - table.set("cellpadding", "2") # Set cellpadding to 2 - tr = etree.SubElement(table, "tr") # Add child tr to table - td1 = etree.SubElement(tr, "td") # Add child td1 to tr - td1.text = markdown.util.AtomicString("Cell content") # Add plain text content - td2 = etree.SubElement(tr, "td") # Add second td to tr - td2.text = "*text* with **inline** formatting." # Add markup text - table.tail = "Text after table" # Add text after table - -You can also manipulate an existing tree. Consider the following example which +```python +table = etree.Element("table") +table.set("cellpadding", "2") # Set cellpadding to 2 +tr = etree.SubElement(table, "tr") # Add child tr to table +td1 = etree.SubElement(tr, "td") # Add child td1 to tr +td1.text = markdown.util.AtomicString("Cell content") # Add plain text content +td2 = etree.SubElement(tr, "td") # Add second td to tr +td2.text = "*text* with **inline** formatting." # Add markup text +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: - def set_link_class(self, element): - for child in element: - if child.tag == "a": - child.set("class", "myclass") #set the class attribute - set_link_class(child) # run recursively on children +```python +def set_link_class(self, element): + for child in element: + if child.tag == "a": + child.set("class", "myclass") #set the class attribute + set_link_class(child) # run recursively on children +``` For more information about working with ElementTree see the ElementTree -[Documentation](http://effbot.org/zone/element-index.htm) +[Documentation](http://effbot.org/zone/element-index.htm) ([Python Docs](http://docs.python.org/lib/module-xml.etree.ElementTree.html)). -Integrating Your Code Into Markdown {: #integrating_into_markdown } -------------------------------------------------------------------- +## 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. +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 -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. -Therefore, the various types of processors and patterns are stored within an -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 +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. +Therefore, the various types of processors and patterns are stored within an +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 } -The `extendMarkdown` method of a `markdown.extensions.Extension` class +The `extendMarkdown` method of a `markdown.extensions.Extension` class accepts two arguments: * **`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 + 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` @@ -426,23 +432,25 @@ accepts two arguments: Contains all the various global variables within the markdown module. !!! Warning - With access to the above items, theoretically you have the option to - change anything through various [monkey_patching][] techniques. However, - you should be aware that the various undocumented parts of markdown may + With access to the above items, theoretically you have the option to + change anything through various [monkey_patching][] techniques. However, + you should be aware that the various undocumented 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 + 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 A simple example: - from markdown.extensions import Extension +```python +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') +class MyExtension(Extension): + def extendMarkdown(self, md, md_globals): + # Insert instance of 'mypattern' before 'references' pattern + md.inlinePatterns.add('mypattern', MyPattern(md), '<references') +``` ### OrderedDict {: #ordereddict } @@ -451,15 +459,15 @@ items. The items are ordered in the order in which they were appended to the OrderedDict. However, an item can also be inserted into the OrderedDict 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 +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. -Generally speaking, within Markdown extensions you will be using the special -helper method `add()` to add additional items to an existing OrderedDict. +Generally speaking, within Markdown extensions you will be using the special +helper method `add()` to add additional items to an existing OrderedDict. The `add()` method accepts three arguments: @@ -467,47 +475,53 @@ The `add()` method accepts three arguments: * **`value`**: The object instance stored in this item. -* **`location`**: The items location in relation to other items. +* **`location`**: 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 - beginning or end of the OrderedDict respectively. - - * A less-than sign (`<`) followed by an existing key (i.e.: + * 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 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: - >>> 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') - >>> od.items() - [("one", 1), ("three", 3), ("four", 4)] +```pycon +>>> 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') +>>> od.items() +[("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' - >>> od.values() - [1, 2, 3, 4] +```pycon +>>> od.add('two', 2, '>one') # Insert after 'one' +>>> od.values() +[1, 2, 3, 4] +``` Now let's insert another item. - >>> od.add('two-point-five', 2.5, '<three') # Insert before 'three' - >>> od.keys() - ["one", "two", "two-point-five", "three", "four"] +```pycon +>>> od.add('two-point-five', 2.5, '<three') # Insert before 'three' +>>> od.keys() +["one", "two", "two-point-five", "three", "four"] +``` 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 +(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 "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 @@ -515,30 +529,40 @@ extension components to the various markdown OrderedDicts. Once an OrderedDict is created, the items are available via key: - MyNode = od['somekey'] +```python +MyNode = od['somekey'] +``` Therefore, to delete an existing item: - del od['somekey'] +```python +del od['somekey'] +``` To change the value of an existing item (leaving location unchanged): - od['somekey'] = MyNewObject() +```python +od['somekey'] = MyNewObject() +``` To change the location of an existing item: - t.link('somekey', '<otherkey') +```python +t.link('somekey', '<otherkey') +``` ### registerExtension {: #registerextension } 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][] +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) +```python +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 @@ -547,15 +571,16 @@ 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 +To register an extension, call `md.registerExtension` from within your `extendMarkdown` method: +```python +def extendMarkdown(self, md, md_globals): + md.registerExtension(self) + # insert processors and patterns here +``` - 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 initialized the first time. Keep that in mind when over-riding the extension's @@ -564,104 +589,117 @@ initialized the first time. Keep that in mind when over-riding the extension's ### 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 +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): - self.config = {'option1' : ['value1', 'description1'], - 'option2' : ['value2', 'description2'] } - super(MyExtension, self).__init__(**kwargs) +```python +class MyExtension(markdown.extensions.Extension): + def __init__(self, **kwargs): + self.config = {'option1' : ['value1', 'description1'], + 'option2' : ['value2', 'description2'] } + super(MyExtension, self).__init__(**kwargs) +``` -When implemented this way the configuration 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']) +```python +markdown.Markdown(extensions=[MyExtension(option1='other value']) +``` -Note that if a keyword is passed in that is not already defined in +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 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. + 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()`**: - Returns a dict of all key/value pairs. + Returns a dict of all key/value pairs. * **`getConfigInfo()`**: - Returns all configuration descriptions as a list of tuples. + Returns all configuration descriptions as a list of tuples. * **`setConfig(key, value)`**: - - 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 - the previous value of `key` is `None`, then `value` is converted to - a Boolean value except when it is `None`. No conversion takes place - when the previous value of `key` is a string. + + 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 + the previous value of `key` is `None`, then `value` is converted to + a Boolean value except when it is `None`. No conversion takes place + when the previous value of `key` is a string. * **`setConfigs(items)`**: - Sets multiple configuration settings given a dict of key/value pairs. + Sets multiple configuration settings given a dict of key/value pairs. ### `makeExtension` {: #makeextension } As noted in the [library reference] an instance of an extension can be passed -directly to Markdown. In fact, this is the preferred way to use third-party +directly to Markdown. In fact, this is the preferred way to use third-party extensions. For example: - import markdown - import myextension - myext = myextension.MyExtension(option='value') - md = markdown.Markdown(extensions=[myext]) +```python +import markdown +import myextension +myext = myextension.MyExtension(option='value') +md = markdown.Markdown(extensions=[myext]) +``` -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). +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). The "name" of your extension must be a string consisting of the importable path to your module using Python's dot notation. Therefore, if you are providing a library -to your users and would like to include a custom markdown extension within your +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 separated by a colon. Therefore, if you were to import the class like this: - - from path.to.module import SomeExtensionClass + +```python +from path.to.module import SomeExtensionClass +``` Then the named extension would comprise this string: - "path.to.module:SomeExtensionClass" +```python +"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. -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 -that your users include the class name in their string, you must define only one extension -per module and that module must contain a module-level function called `makeExtension` -that accepts `**kwargs` and returns an extension instance. +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 that your users include the class name in their string, you +must define only one extension per module and that module must contain a +module-level function called `makeExtension` that accepts `**kwargs` and returns +an extension instance. For example: - class MyExtension(markdown.extensions.Extension) - # Define extension here... - - def makeExtension(**kwargs): - return MyExtension(**kwargs) +```python +class MyExtension(markdown.extensions.Extension) + # Define extension here... -When Markdown is passed the "name" of your extension as a dot notation string, it will import -the module and call the `makeExtension` function to initiate your extension. +def makeExtension(**kwargs): + return MyExtension(**kwargs) +``` +When Markdown is passed the "name" of your extension as a dot notation string, +it will import the module and call the `makeExtension` function to initiate your +extension. [Preprocessors]: #preprocessors [Inline Patterns]: #inlinepatterns @@ -676,7 +714,7 @@ the module and call the `makeExtension` function to initiate your extension. [Config Settings]: #configsettings [makeExtension]: #makeextension [ElementTree]: http://effbot.org/zone/element-index.htm -[Available Extensions]: index.html -[Footnotes]: footnotes.html -[Definition Lists]: definition_lists.html -[library reference]: ../reference.html +[Available Extensions]: index.md +[Footnotes]: https://github.com/Python-Markdown/mdx_footnotes +[Definition Lists]: https://github.com/Python-Markdown/mdx_definition_lists +[library reference]: ../reference.md diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.md index 1951347..7b2e19f 100644 --- a/docs/extensions/attr_list.txt +++ b/docs/extensions/attr_list.md @@ -1,36 +1,31 @@ -title: Attribute Lists Extension -prev_title: Abbreviations Extension -prev_url: abbreviations.html -next_title: Definition Lists Extension -next_url: definition_lists.html +title: Attribute Lists Extension -Attribute Lists -=============== +# Attribute Lists -Summary -------- +## Summary The Attribute Lists extension adds a syntax to define attributes on the various HTML elements in markdown's output. This extension is included in the standard Markdown library. -Syntax ------- +## Syntax The basic syntax was inspired by [Maruku][]'s Attribute Lists feature. [Maruku]: http://maruku.rubyforge.org/proposal.html#attribute_lists -### The List ### +### The List An example attribute list might look like this: - {: #someid .someclass somekey='some value' } +```text +{: #someid .someclass somekey='some value' } +``` A word which starts with a hash (`#`) will set the id of an element. -A word which starts with a dot (`.`) will be added to the list of classes +A word which starts with a dot (`.`) will be added to the list of classes assigned to an element. A key/value pair (`somekey='some value'`) will assign that pair to the element. @@ -38,51 +33,66 @@ A key/value pair (`somekey='some value'`) will assign that pair to the element. Be aware that while the dot syntax will add to a class, using key/value pairs will always override the previously defined attribute. Consider the following: - {: #id1 .class1 id=id2 class="class2 class3" .class4 } +```text +{: #id1 .class1 id=id2 class="class2 class3" .class4 } +``` The above example would result in the following attributes being defined: - id="id2" class="class2 class3 class4" +```text +id="id2" class="class2 class3 class4" +``` -### Block Level ### +### Block Level To define attributes for a block level element, the attribute list should be defined on the last line of the block by itself. - This is a paragraph. - {: #an_id .a_class } +```text +This is a paragraph. +{: #an_id .a_class } +``` The above results in the following output: - <p id="an_id" class="a_class">This is a paragraph.</p> +```html +<p id="an_id" class="a_class">This is a paragraph.</p> +``` The one exception is headers, as they are only ever allowed on one line. - A setext style header {: #setext} - ================================= +```text +A setext style header {: #setext} +================================= - ### A hash style header ### {: #hash } +### A hash style header ### {: #hash } +``` The above results in the following output: - <h1 id="setext">A setext style header</h1> - <h3 id="hash">A hash style header</h3> +```html +<h1 id="setext">A setext style header</h1> +<h3 id="hash">A hash style header</h3> +``` -### Inline ### +### Inline -To define attributes on inline elements, the attribute list should be defined +To define attributes on inline elements, the attribute list should be defined immediately after the inline element with no white space. - [link](http://example.com){: class="foo bar" title="Some title!" } +```text +[link](http://example.com){: class="foo bar" title="Some title!" } +``` The above results in the following output: - <p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p> +```html +<p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p> +``` -Usage ------ +## Usage -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.attr_list` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.attr_list` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.md index c2980f2..6490dcc 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.md @@ -1,14 +1,8 @@ -title: CodeHilite Extension -prev_title: Admonition Extension -prev_url: admonition.html -next_title: HeaderId Extension -next_url: header_id.html +title: CodeHilite Extension -CodeHilite -========== +# CodeHilite -Summary -------- +## Summary The CodeHilite extension adds code/syntax highlighting to standard Python-Markdown code blocks using [Pygments][]. @@ -17,10 +11,9 @@ Python-Markdown code blocks using [Pygments][]. This extension is included in the standard Markdown library. -Setup ------ +## Setup -### Step 1: Download and Install Pygments ### +### Step 1: Download and Install Pygments You will also need to [download][dl] and install the Pygments package on your `PYTHONPATH`. The CodeHilite extension will produce HTML output without @@ -29,14 +22,16 @@ Pygments, but it won't highlight anything (same behavior as setting [dl]: http://pygments.org/download/ -### Step 2: Add CSS Classes ### +### Step 2: Add CSS Classes You will need to define the appropriate CSS classes with appropriate rules. The CSS rules either need to be defined in or linked from the header of your HTML templates. Pygments can generate CSS rules for you. Just run the following command from the command line: - pygmentize -S default -f html -a .codehilite > styles.css +```bash +pygmentize -S default -f html -a .codehilite > styles.css +``` If you are using a different `css_class` (default: `.codehilite`), then set the value of the `-a` option to that class name. The CSS rules will be @@ -47,7 +42,9 @@ If you would like to use a different theme, swap out `default` for the desired theme. For a list of themes installed on your system (additional themes can be installed via Pygments plugins), run the following command: - pygmentize -L style +```bash +pygmentize -L style +``` See Pygments' excellent [documentation] for more details. If no language is defined, Pygments will attempt to guess the language. When that fails, the code @@ -68,9 +65,7 @@ block will not be highlighted. [preview]: http://richleland.github.io/pygments-css/ [documentation]: http://pygments.org/docs/ - -Syntax ------- +## Syntax The CodeHilite extension follows the same [syntax][] as regular Markdown code blocks, with one exception. The highlighter needs to know what language to use for @@ -86,43 +81,51 @@ code 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 code block contains a shebang, the language is derived from that and line numbers are used. - #!/usr/bin/python - # Code goes here ... +```md + #!/usr/bin/python + # Code goes here ... +``` 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 block before processing. Line numbers are used. - #!python - # Code goes here ... +```md + #!python + # Code goes here ... +``` Will result in: + #!python # Code goes here ... -### Colons ### +### Colons If the first line begins with three or more colons, the text following the colons identifies the language. The first line is removed from the code block before processing and line numbers are not used. - :::python - # Code goes here ... +```md + :::python + # Code goes here ... +``` Will result in: + :::python # Code goes here ... Certain lines can be selected for emphasis with the colon syntax. When @@ -137,13 +140,15 @@ This is useful to direct the reader's attention to specific lines. !!! Note `hl_lines` is named for Pygments' option meaning "highlighted lines". -### When No Language is Defined ### +### When No Language is Defined CodeHilite is completely backwards compatible so that if a code block is encountered that does not define a language, the block is simply wrapped in `<pre>` tags and output. - # Code goes here ... +```md + # Code goes here ... +``` Will result in: @@ -151,21 +156,22 @@ Will result in: Lets see the source for that: - <div class="codehilite"><pre><code># Code goes here ... - </code></pre></div> +```html +<div class="codehilite"><pre><code># Code goes here ... +</code></pre></div> +``` !!! Note When no language is defined, the Pygments highlighting engine will try to guess the language (unless `guess_lang` is set to `False`). Upon failure, the same behavior will happen as described above. -Usage ------ +## Usage -See [Extensions](index.html) for general extension usage, specify +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.codehilite` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: diff --git a/docs/extensions/definition_lists.md b/docs/extensions/definition_lists.md new file mode 100644 index 0000000..e9f8984 --- /dev/null +++ b/docs/extensions/definition_lists.md @@ -0,0 +1,52 @@ +title: Definition Lists Extension + +Definition Lists +================ + +Summary +------- + +The Definition Lists extension adds the ability to create definition lists in +Markdown documents. + +This extension is included in the standard Markdown library. + +Syntax +------ + +Definition lists are defined using the syntax established in +[PHP Markdown Extra][php]. + +[php]: http://www.michelf.com/projects/php-markdown/extra/#def-list + +Thus, the following text (taken from the above referenced PHP documentation): + +```md +Apple +: Pomaceous fruit of plants of the genus Malus in + the family Rosaceae. + +Orange +: The fruit of an evergreen tree of the genus Citrus. +``` + +will be rendered as: + +```html +<dl> +<dt>Apple</dt> +<dd>Pomaceous fruit of plants of the genus Malus in +the family Rosaceae.</dd> + +<dt>Orange</dt> +<dd>The fruit of an evergreen tree of the genus Citrus.</dd> +</dl> +``` + +Usage +----- + +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.def_list` as the name of the extension. + +This extension does not accept any special configuration options. diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.txt deleted file mode 100644 index d7003e2..0000000 --- a/docs/extensions/definition_lists.txt +++ /dev/null @@ -1,53 +0,0 @@ -title: Definition Lists Extension -prev_title: Attribute Lists Extension -prev_url: attr_list.html -next_title: Fenced Code Blocks Extension -next_url: fenced_code_blocks.html - -Definition Lists -================ - -Summary -------- - -The Definition Lists extension adds the ability to create definition lists in -Markdown documents. - -This extension is included in the standard Markdown library. - -Syntax ------- - -Definition lists are defined using the syntax established in -[PHP Markdown Extra][php]. - -[php]: http://www.michelf.com/projects/php-markdown/extra/#def-list - -Thus, the following text (taken from the above referenced PHP documentation): - - Apple - : Pomaceous fruit of plants of the genus Malus in - the family Rosaceae. - - Orange - : The fruit of an evergreen tree of the genus Citrus. - -will be rendered as: - - <dl> - <dt>Apple</dt> - <dd>Pomaceous fruit of plants of the genus Malus in - the family Rosaceae.</dd> - - <dt>Orange</dt> - <dd>The fruit of an evergreen tree of the genus Citrus.</dd> - </dl> - - -Usage ------ - -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.def_list` -as the name of the extension. - -This extension does not accept any special configuration options. diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.md index 5347d81..0639d3d 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.md @@ -1,49 +1,43 @@ -title: Extra Extension -prev_title: Extensions -prev_url: index.html -next_title: Abbreviations Extension -next_url: abbreviations.html +title: Extra Extension -Python-Markdown Extra -===================== +# Python-Markdown Extra -Summary -------- +## Summary A compilation of various Python-Markdown extensions that (mostly) imitates [PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/). The supported extensions include: -* [Abbreviations](abbreviations.html) -* [Attribute Lists](attr_list.html) -* [Definition Lists](definition_lists.html) -* [Fenced Code Blocks](fenced_code_blocks.html) -* [Footnotes](footnotes.html) -* [Tables](tables.html) -* [Smart Strong](smart_strong.html) +* [Abbreviations](abbreviations.md) +* [Attribute Lists](attr_list.md) +* [Definition Lists](definition_lists.md) +* [Fenced Code Blocks](fenced_code_blocks.md) +* [Footnotes](footnotes.md) +* [Tables](tables.md) +* [Smart Strong](smart_strong.md) -See each individual extension for syntax documentation. Extra and all its +See each individual extension for syntax documentation. Extra and all its supported extensions are included in the standard Markdown library. -Usage ------ +## Usage From the Python interpreter: - >>> import markdown - >>> html = markdown.markdown(text, ['markdown.extensions.extra']) +```pycon +>>> import markdown +>>> html = markdown.markdown(text, ['markdown.extensions.extra']) +``` -There may be [additional extensions](index.html) that are distributed with -Python-Markdown that are not included here in Extra. The features -of those extensions are not part of PHP Markdown Extra, and -therefore, not part of Python-Markdown Extra. If you really would -like Extra to include additional extensions, we suggest creating -your own clone of Extra under a different name -(see the [Extension API](api.html)). +There may be [additional extensions](index.md) that are distributed with +Python-Markdown that are not included here in Extra. The features +of those extensions are not part of PHP Markdown Extra, and +therefore, not part of Python-Markdown Extra. If you really would +like Extra to include additional extensions, we suggest creating +your own clone of Extra under a different name +(see the [Extension API](api.md)). -Markdown Inside HTML Blocks ---------------------------- +### 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. @@ -60,15 +54,18 @@ regardless of tag. If the default is overridden by a value of `block`, *block parsing will occur* regardless of tag. #### Simple Example: -``` + +```md This is *true* markdown text. <div markdown="1"> This is *true* markdown text. </div> ``` + #### Result: -``` + +```html <p>This is <em>true</em> markdown text.</p> <div> <p>This is <em>true</em> markdown text.</p> @@ -76,6 +73,7 @@ This is *true* markdown text. ``` ### Nested Markdown Inside HTML Blocks + Nested elements are more sensitive and must be used cautiously. To avoid unexpected results: @@ -84,7 +82,8 @@ unexpected results: * Only have one level of nesting. #### Complex Example: -``` + +```md <div markdown="1" name="Example"> The text of the `Example` element. @@ -120,8 +119,10 @@ Raw HTML blocks may also be nested. This text is after the markdown in HTML. ``` -#### Result: -``` + +#### Complex Result: + +```html <div name="Example"> <p>The text of the <code>Example</code> element.</p> <div name="DefaultBlockMode"> diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.md index 982f5d4..b7a657e 100644 --- a/docs/extensions/fenced_code_blocks.txt +++ b/docs/extensions/fenced_code_blocks.md @@ -1,37 +1,32 @@ -title: Fenced Code Blocks Extension -prev_title: Definition Lists Extension -prev_url: definition_lists.html -next_title: Footnotes Extension -next_url: footnotes.html +title: Fenced Code Blocks Extension -Fenced Code Blocks -================== +# Fenced Code Blocks -Summary -------- +## Summary The Fenced Code Blocks extension adds a secondary way to define code blocks, which overcomes a few limitations of the indented code blocks. This extension is included in the standard Markdown library. -Syntax ------- +## Syntax -Fenced Code Blocks are defined using the syntax established in +Fenced Code Blocks are defined using the syntax established in [PHP Markdown Extra][php]. [php]: http://www.michelf.com/projects/php-markdown/extra/#fenced-code-blocks Thus, the following text (taken from the above referenced PHP documentation): - This is a paragraph introducing: +```md +This is a paragraph introducing: +~~~~~~~~~~~~~~~~~~~~ +a one-line code block ~~~~~~~~~~~~~~~~~~~~ - a one-line code block - ~~~~~~~~~~~~~~~~~~~~ +``` -Fenced code blocks can have a blank line as the first and/or last line of a +Fenced code blocks can have a blank line as the first and/or last line of a code block and they can also come immediately after a list item without becoming part of the list. @@ -40,42 +35,48 @@ part of the list. Fenced Code Blocks are only supported at the document root level. Therefore, they cannot be nested inside lists or blockquotes. -### Language ### +### Language -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 -with other markdown syntax, the language can *optionally* be wrapped in curly +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 +with other markdown syntax, the language can *optionally* be wrapped in curly brackets: - ~~~~{.python} - # python code - ~~~~ +```md +~~~~{.python} +# python code +~~~~ - ~~~~.html - <p>HTML Document</p> - ~~~~ +~~~~.html +<p>HTML Document</p> +~~~~ +``` The above will output: - <pre><code class="python"># python code - </code></pre> - - <pre><code class="html"><p>HTML Document</p> - </code></pre> +```html +<pre><code class="python"># python code +</code></pre> + +<pre><code class="html"><p>HTML Document</p> +</code></pre> +``` [GitHub][]'s backtick (`\``) syntax is also supported: - ```python - # more python code - ``` +````md +```python +# more python code +``` +```` [GitHub]: http://github.github.com/github-flavored-markdown/ -### Emphasized Lines ### +### Emphasized Lines -If you would like to have your fenced code blocks highlighted with the +If you would like to have your fenced code blocks highlighted with the [CodeHilite][] extension, simply enable that extension (remember that [Pygments][] is its dependency) and the language of your fenced code blocks will be passed in and highlighted appropriately. @@ -85,28 +86,31 @@ can also have emphasized certain lines of code. The lines can be specified with PHP Extra's syntax: - ~~~~{.python hl_lines="1 3"} - # This line is emphasized - # This line isn't - # This line is emphasized - ~~~~ +```md +~~~~{.python hl_lines="1 3"} +# This line is emphasized +# This line isn't +# This line is emphasized +~~~~ +``` ... or with GitHub's: - ```python hl_lines="1 3" - # This line is emphasized - # This line isn't - # This line is emphasized - ``` +````md +```python hl_lines="1 3" +# This line is emphasized +# This line isn't +# This line is emphasized +``` +```` [CodeHilite]: code_hilite.html [Pygments]: http://pygments.org/ [colon]: code_hilite.html#colons -Usage ------ +## Usage -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.fenced_code` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.fenced_code` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.md index e9b0451..c94c2c4 100644 --- a/docs/extensions/footnotes.txt +++ b/docs/extensions/footnotes.md @@ -1,8 +1,4 @@ -title: Footnotes Extension -prev_title: Fenced Code Blocks Extension -prev_url: fenced_code_blocks.html -next_title: Tables Extension -next_url: tables.html +title: Footnotes Extension Footnotes ========= @@ -18,56 +14,59 @@ This extension is included in the standard Markdown library. Syntax ------ -Python-Markdown's Footnote syntax follows the generally accepted syntax of the +Python-Markdown's Footnote syntax follows the generally accepted syntax of the Markdown community at large and almost exactly matches [PHP Markdown Extra][]'s -implementation of footnotes. The only differences involve a few subtleties in +implementation of footnotes. The only differences involve a few subtleties in the output. [PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#footnotes Example: - Footnotes[^1] have a label[^@#$%] and the footnote's content. +```md +Footnotes[^1] have a label[^@#$%] and the footnote's content. - [^1]: This is a footnote content. - [^@#$%]: A footnote on the label: "@#$%". +[^1]: This is a footnote content. +[^@#$%]: A footnote on the label: "@#$%". +``` -A footnote label must start with a caret `^` and may contain any inline text +A footnote label must start with a caret `^` and may contain any inline text (including spaces) between a set of square brackets `[]`. Only the first caret has any special meaning. -A footnote content must start with the label followed by a colon and at least +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 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 -one tab). - -When working with multiple blocks, it may be helpful to start the content on a -separate line from the label which defines the content. This way the entire block +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 +one tab). + +When working with multiple blocks, it may be helpful to start the content on a +separate line from the label which defines the content. This way the entire block is indented consistently and any errors are more easily discernible by the author. - [^1]: - The first paragraph of the definition. +```md +[^1]: + The first paragraph of the definition. - Paragraph two of the definition. + Paragraph two of the definition. - > A blockquote with - > multiple lines. + > A blockquote with + > multiple lines. - a code block - - A final paragraph. + a code block + A final paragraph. +``` Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.footnotes` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.footnotes` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: @@ -82,7 +81,7 @@ The following options are provided to configure the output: * **`UNIQUE_IDS`**: Whether to avoid collisions across multiple calls to `reset()`. Defaults to `False`. - + * **`BACKLINK_TEXT`**: The text string that links from the footnote definition back to the position in the document. Defaults to `↩`. diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.md index 5557b1b..82e8e2c 100644 --- a/docs/extensions/header_id.txt +++ b/docs/extensions/header_id.md @@ -1,8 +1,4 @@ -title: HeaderId Extension -prev_title: CodeHilite Extension -prev_url: code_hilite.html -next_title: Meta-Data Extension -next_url: meta_data.html +title: HeaderId Extension HeaderId ======== @@ -19,33 +15,37 @@ This extension is included in the standard Markdown library. This extension is **Pending Deprecation**. The [Table of Contents][toc] Extension should be used instead, which offers most the features of this extension and more. - -[toc]: toc.html + +[toc]: toc.md Syntax ------ -By default, all headers will automatically have unique `id` attributes -generated based upon the text of the header (see below to turn this off). +By default, all headers will automatically have unique `id` attributes +generated based upon the text of the header (see below to turn this off). Note this example, in which all three headers would have the same `id`: - #Header - #Header - #Header +```md +#Header +#Header +#Header +``` Results in: - <h1 id="header">Header</h1> - <h1 id="header_1">Header</h1> - <h1 id="header_2">Header</h1> +```html +<h1 id="header">Header</h1> +<h1 id="header_1">Header</h1> +<h1 id="header_2">Header</h1> +``` Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.headerid` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.headerid` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: @@ -55,10 +55,11 @@ 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: + :::pycon >>> text = ''' ... #Some Header ... ## Next Level''' @@ -72,10 +73,11 @@ The following options are provided to configure the output: Default: `True` - The `forceid` setting turns on or off the automatically generated ids for + The `forceid` setting turns on or off the automatically generated ids for headers that do not have one explicitly defined (using the - [Attribute List](attr_list.html) extension). + [Attribute List](attr_list.md) extension). + :::pycon >>> text = ''' ... # Some Header ... # Header with ID # { #foo }''' @@ -103,24 +105,27 @@ The following options are provided to configure the output: Using with Meta-Data -------------------- -The HeaderId extension also supports the [Meta-Data](meta_data.html) extension. -Please see the documentation for that extension for specifics. The supported +The HeaderId extension also supports the [Meta-Data](meta_data.md) extension. +Please see the documentation for that extension for specifics. The supported meta-data keywords are: * `header_level` * `header_forceid` -When used, the meta-data will override the settings provided through the -`extension_configs` interface. +When used, the meta-data will override the settings provided through the +`extension_configs` interface. This document: - header_level: 2 - header_forceid: Off - - # A Header +```md +header_level: 2 +header_forceid: Off +# A Header +``` Will result in the following output: - <h2>A Header</h2> +```html +<h2>A Header</h2> +``` diff --git a/docs/extensions/index.txt b/docs/extensions/index.md index ba95274..34f8084 100644 --- a/docs/extensions/index.txt +++ b/docs/extensions/index.md @@ -1,9 +1,4 @@ -title: Extensions -prev_title: Command Line -prev_url: ../cli.html -next_title: Extra Extension -next_url: extra.html - +title: Extensions Available Extensions ==================== @@ -14,19 +9,23 @@ actual source files. To use an extension, pass it to markdown with the `extensions` keyword. - markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes']) +```python +markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'markdown.extensions.footnotes']) +``` -See the [Library Reference](../reference.html#extensions) for more details. +See the [Library Reference](../reference.md#extensions) for more details. -From the command line, specify an extension with the `-x` option. +From the command line, specify an extension with the `-x` option. - $ python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html +```bash +python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.tables input.txt > output.html +``` -See the [Command Line docs](../cli.html) or use the `--help` option for more details. +See the [Command Line docs](../cli.md) or use the `--help` option for more details. !!! seealso "See Also" If you would like to write your own extensions, see the - [Extension API](api.html) for details. + [Extension API](api.md) for details. Officially Supported Extensions ------------------------------- @@ -57,23 +56,23 @@ Extension | "Name" [Table of Contents] | `markdown.extensions.toc` [WikiLinks] | `markdown.extensions.wikilinks` -[Extra]: extra.html -[Abbreviations]: abbreviations.html -[Attribute Lists]: attr_list.html -[Definition Lists]: definition_lists.html -[Fenced Code Blocks]: fenced_code_blocks.html -[Footnotes]: footnotes.html -[Tables]: tables.html -[Smart Strong]: smart_strong.html -[Admonition]: admonition.html -[CodeHilite]: code_hilite.html -[HeaderId]: header_id.html -[Meta-Data]: meta_data.html -[New Line to Break]: nl2br.html -[Sane Lists]: sane_lists.html -[SmartyPants]: smarty.html -[Table of Contents]: toc.html -[WikiLinks]: wikilinks.html +[Extra]: extra.md +[Abbreviations]: abbreviations.md +[Attribute Lists]: attr_list.md +[Definition Lists]: definition_lists.md +[Fenced Code Blocks]: fenced_code_blocks.md +[Footnotes]: footnotes.md +[Tables]: tables.md +[Smart Strong]: smart_strong.md +[Admonition]: admonition.md +[CodeHilite]: code_hilite.md +[HeaderId]: header_id.md +[Meta-Data]: meta_data.md +[New Line to Break]: nl2br.md +[Sane Lists]: sane_lists.md +[SmartyPants]: smarty.md +[Table of Contents]: toc.md +[WikiLinks]: wikilinks.md Third Party Extensions ---------------------- diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.md index 4a4fe62..36d5e7a 100644 --- a/docs/extensions/meta_data.txt +++ b/docs/extensions/meta_data.md @@ -1,8 +1,4 @@ -title: Meta-Data Extension -prev_title: HeaderId Extension -prev_url: header_id.html -next_title: New Line to Break Extension -next_url: nl2br.html +title: Meta-Data Extension Meta-Data ========= @@ -23,26 +19,28 @@ This extension is included in the standard Markdown library. Syntax ------ -Meta-data consists of a series of keywords and values defined at the beginning +Meta-data consists of a series of keywords and values defined at the beginning of a markdown document like this: - Title: My Document - Summary: A brief description of my document. - Authors: Waylan Limberg - John Doe - Date: October 2, 2007 - blank-value: - base_url: http://example.com +```md +Title: My Document +Summary: A brief description of my document. +Authors: Waylan Limberg + John Doe +Date: October 2, 2007 +blank-value: +base_url: http://example.com - This is the first paragraph of the document. +This is the first paragraph of the document. +``` -The keywords are case-insensitive and may consist of letters, numbers, -underscores and dashes and must end with a colon. The values consist of +The keywords are case-insensitive and may consist of letters, numbers, +underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank. If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as -many lines as desired. +many lines as desired. The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank. @@ -59,36 +57,38 @@ by Markdown. Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.meta` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.meta` as the name of the extension. Accessing the Meta-Data ----------------------- -The meta-data is made available as a python Dict in the `Meta` attribute of an +The meta-data is made available as a python Dict in the `Meta` attribute of an instance of the Markdown class. For example, using the above document: - >>> md = markdown.Markdown(extensions = ['markdown.extensions.meta']) - >>> html = md.convert(text) - >>> # Meta-data has been stripped from output - >>> print html - <p>This is the first paragraph of the document.</p> - - >>> # View meta-data - >>> print md.Meta - { - 'title' : ['My Document'], - 'summary' : ['A brief description of my document.'], - 'authors' : ['Waylan Limberg', 'John Doe'], - 'date' : ['October 2, 2007'], - 'blank-value' : [''], - 'base_url' : ['http://example.com'] - } - -Note that the keys are all lowercase and the values consist of a list of -strings where each item is one line for that key. This way, one could preserve -line breaks if desired. Or the items could be joined where appropriate. No -assumptions are made regarding the data. It is simply passed as found to the +```pycon +>>> md = markdown.Markdown(extensions = ['markdown.extensions.meta']) +>>> html = md.convert(text) +>>> # Meta-data has been stripped from output +>>> print html +<p>This is the first paragraph of the document.</p> + +>>> # View meta-data +>>> print md.Meta +{ +'title' : ['My Document'], +'summary' : ['A brief description of my document.'], +'authors' : ['Waylan Limberg', 'John Doe'], +'date' : ['October 2, 2007'], +'blank-value' : [''], +'base_url' : ['http://example.com'] +} +``` + +Note that the keys are all lowercase and the values consist of a list of +strings where each item is one line for that key. This way, one could preserve +line breaks if desired. Or the items could be joined where appropriate. No +assumptions are made regarding the data. It is simply passed as found to the `Meta` attribute. Perhaps the meta-data could be passed into a template system, or used by @@ -98,14 +98,13 @@ the developer. Compatible Extensions --------------------- -The following extensions are currently known to work with the Meta-Data +The following extensions are currently known to work with the Meta-Data extension. The keywords they are known to support are also listed. -* [HeaderId](header_id.html) +* [HeaderId](header_id.md) * `header_level` * `header_forceid` -* [WikiLinks](wikilinks.html) +* [WikiLinks](wikilinks.md) * `wiki_base_url` * `wiki_end_url` * `wiki_html_class` - diff --git a/docs/extensions/nl2br.md b/docs/extensions/nl2br.md new file mode 100644 index 0000000..4f5e611 --- /dev/null +++ b/docs/extensions/nl2br.md @@ -0,0 +1,35 @@ +title: New Line to Break Extension + +New-Line-to-Break Extension +=========================== + +Summary +------- + +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/ + +Example +------- + +```pycon +>>> import markdown +>>> text = """ +... Line 1 +... Line 2 +... """ +>>> html = markdown.markdown(text, extensions=['markdown.extensions.nl2br']) +>>> print html +<p>Line 1<br /> +Line 2</p> +``` + +Usage +----- + +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.nl2br` as the name of the extension. + +This extension does not accept any special configuration options. diff --git a/docs/extensions/nl2br.txt b/docs/extensions/nl2br.txt deleted file mode 100644 index 8ba27c8..0000000 --- a/docs/extensions/nl2br.txt +++ /dev/null @@ -1,37 +0,0 @@ -title: New Line to Break Extension -prev_title: Meta-Data Extension -prev_url: meta_data.html -next_title: Sane Lists Extension -next_url: sane_lists.html - -New-Line-to-Break Extension -=========================== - -Summary -------- - -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/ - -Example -------- - - >>> import markdown - >>> text = """ - ... Line 1 - ... Line 2 - ... """ - >>> html = markdown.markdown(text, extensions=['markdown.extensions.nl2br']) - >>> print html - <p>Line 1<br /> - Line 2</p> - -Usage ------ - -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.nl2br` -as the name of the extension. - -This extension does not accept any special configuration options. diff --git a/docs/extensions/sane_lists.txt b/docs/extensions/sane_lists.md index 8f713d0..49a7a85 100644 --- a/docs/extensions/sane_lists.txt +++ b/docs/extensions/sane_lists.md @@ -1,8 +1,4 @@ -title: Sane Lists Extension -prev_title: New Line to Break Extension -prev_url: nl2br.html -next_title: SmartyPants Extension -next_url: smarty.html +title: Sane Lists Extension Sane Lists ========== @@ -22,52 +18,60 @@ Sane Lists do not allow the mixing of list types. In other words, an ordered list will not continue when an unordered list item is encountered and vice versa. For example: - 1. Ordered item 1 - 2. Ordered item 2 +```md +1. Ordered item 1 +2. Ordered item 2 - * Unordered item 1 - * Unordered item 2 +* Unordered item 1 +* Unordered item 2 +``` will result in the following output: - <ol> - <li>Ordered item 1</li> - <li>Ordered item 2</li> - </ol> +```html +<ol> + <li>Ordered item 1</li> + <li>Ordered item 2</li> +</ol> - <ul> - <li>Unordered item 1</li> - <li>Unordered item 2</li> - </ul> +<ul> + <li>Unordered item 1</li> + <li>Unordered item 2</li> +</ul> +``` Whereas the default Markdown behavior would be to generate an unordered list. Note that, unlike the default Markdown behavior, if a blank line is not -included between list items, the different list type is ignored completely. +included between list items, the different list type is ignored completely. This corresponds to the behavior of paragraphs. For example: - A Paragraph. - * Not a list item. +```md +A Paragraph. +* Not a list item. - 1. Ordered list item. - * Not a separate list item. +1. Ordered list item. +* Not a separate list item. +``` With this extension the above will result in the following output: - <p>A Paragraph. - * Not a list item.</p> +```html +<p>A Paragraph. +* Not a list item.</p> - <ol> - <li>Ordered list item. - * Not a separate list item.</li> - </ol> +<ol> + <li>Ordered list item. + * Not a separate list item.</li> +</ol> +``` In all other ways, Sane Lists should behave as normal Markdown lists. Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.sane_lists` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.sane_lists` as the name of the extension. This extension does not accept any special configuration options. diff --git a/docs/extensions/smart_strong.md b/docs/extensions/smart_strong.md new file mode 100644 index 0000000..1fb3c68 --- /dev/null +++ b/docs/extensions/smart_strong.md @@ -0,0 +1,39 @@ +title: Smart Strong Extension + +Smart_Strong +============ + +Summary +------- + +The Smart_Strong extension adds smarter handling of double underscores within +words. This does for double underscores what [smart_emphasis][] does for single +underscores. + +The Smart_Strong extension is included in the standard Markdown library. + +[smart_emphasis]: ../reference.md#smart_emphasis + +Example +------- + +```pycon +>>> import markdown +>>> markdown.markdown('Text with double__underscore__words.', \ + extensions=['markdown.extensions.smart_strong']) +u'<p>Text with double__underscore__words.</p>' +>>> markdown.markdown('__Strong__ still works.', \ + extensions=['markdown.extensions.smart_strong']) +u'<p><strong>Strong</strong> still works.</p>' +>>> markdown.markdown('__this__works__too__.', \ + extensions=['markdown.extensions.smart_strong']) +u'<p><strong>this__works__too</strong>.</p>' +``` + +Usage +----- + +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.smart_strong` as the name of the extension. + +This extension does not accept any special configuration options. diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.txt deleted file mode 100644 index e2e5458..0000000 --- a/docs/extensions/smart_strong.txt +++ /dev/null @@ -1,41 +0,0 @@ -title: Smart Strong Extension -prev_title: Tables Extension -prev_url: tables.html -next_title: Admonition Extension -next_url: admonition.html - -Smart_Strong -============ - -Summary -------- - -The Smart_Strong extension adds smarter handling of double underscores within -words. This does for double underscores what [smart_emphasis][] does for single -underscores. - -The Smart_Strong extension is included in the standard Markdown library. - -[smart_emphasis]: ../reference.html#smart_emphasis - -Example -------- - - >>> import markdown - >>> markdown.markdown('Text with double__underscore__words.', \ - extensions=['markdown.extensions.smart_strong']) - u'<p>Text with double__underscore__words.</p>' - >>> markdown.markdown('__Strong__ still works.', \ - extensions=['markdown.extensions.smart_strong']) - u'<p><strong>Strong</strong> still works.</p>' - >>> markdown.markdown('__this__works__too__.', \ - extensions=['markdown.extensions.smart_strong']) - u'<p><strong>this__works__too</strong>.</p>' - -Usage ------ - -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.smart_strong` -as the name of the extension. - -This extension does not accept any special configuration options. diff --git a/docs/extensions/smarty.txt b/docs/extensions/smarty.md index 247658a..8c0d8cc 100644 --- a/docs/extensions/smarty.txt +++ b/docs/extensions/smarty.md @@ -1,8 +1,4 @@ title: SmartyPants Extension -prev_title: Sane Lists Extension -prev_url: sane_lists.html -next_title: Table of Contents Extension -next_url: toc.html SmartyPants =========== @@ -23,42 +19,44 @@ ASCII symbol | Replacements | HTML Entities | Substitution Keys `---` | — | `—` | `'mdash'` Using the configuration option 'substitutions' you can overwrite the -default substitutions. Just pass a dict mapping (a subset of) the +default substitutions. Just pass a dict mapping (a subset of) the keys to the substitution strings. - -For example, one might use the following configuration to get correct quotes for + +For example, one might use the following configuration to get correct quotes for the German language: - extension_configs = { - 'markdown.extensions.smarty': { - 'substitutions': { - 'left-single-quote': '‚', # sb is not a typo! - 'right-single-quote': '‘', - 'left-double-quote': '„', - 'right-double-quote': '“' - } +```python +extension_configs = { + 'markdown.extensions.smarty': { + 'substitutions': { + 'left-single-quote': '‚', # sb is not a typo! + 'right-single-quote': '‘', + 'left-double-quote': '„', + 'right-double-quote': '“' } } +} +``` !!! note - This extension re-implements the Python [SmartyPants] + 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 - [CodeHilite] Extension) like the third party library + it does offer a few advantages. Notably, it will not + try to work on highlighted code blocks (using the + [CodeHilite] Extension) like the third party library has been known to do. - + [SmartyPants]: http://pythonhosted.org/smartypants/ [CodeHilite]: code_hilite.html Usage ----- -See [Extensions](index.html) for general extension usage, specify +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.smarty` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: diff --git a/docs/extensions/tables.md b/docs/extensions/tables.md new file mode 100644 index 0000000..2bea470 --- /dev/null +++ b/docs/extensions/tables.md @@ -0,0 +1,58 @@ +title: Tables Extension + +Tables +====== + +Summary +------- + +The Tables extension adds the ability to create tables in Markdown documents. + +This extension is included in the standard Markdown library. + +Syntax +------ + +Tables are defined using the syntax established in [PHP Markdown Extra][php]. + +[php]: http://www.michelf.com/projects/php-markdown/extra/#table + +Thus, the following text (taken from the above referenced PHP documentation): + +```md +First Header | Second Header +------------- | ------------- +Content Cell | Content Cell +Content Cell | Content Cell +``` + +will be rendered as: + +```html +<table> + <thead> + <tr> + <th>First Header</th> + <th>Second Header</th> + </tr> + </thead> + <tbody> + <tr> + <td>Content Cell</td> + <td>Content Cell</td> + </tr> + <tr> + <td>Content Cell</td> + <td>Content Cell</td> + </tr> + </tbody> +</table> +``` + +Usage +----- + +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.tables` as the name of the extension. + +This extension does not accept any special configuration options. diff --git a/docs/extensions/tables.txt b/docs/extensions/tables.txt deleted file mode 100644 index 759772a..0000000 --- a/docs/extensions/tables.txt +++ /dev/null @@ -1,58 +0,0 @@ -title: Tables Extension -prev_title: Footnotes Extension -prev_url: footnotes.html -next_title: Smart Strong Extension -next_url: smart_strong.html - -Tables -====== - -Summary -------- - -The Tables extension adds the ability to create tables in Markdown documents. - -This extension is included in the standard Markdown library. - -Syntax ------- - -Tables are defined using the syntax established in [PHP Markdown Extra][php]. - -[php]: http://www.michelf.com/projects/php-markdown/extra/#table - -Thus, the following text (taken from the above referenced PHP documentation): - - First Header | Second Header - ------------- | ------------- - Content Cell | Content Cell - Content Cell | Content Cell - -will be rendered as: - - <table> - <thead> - <tr> - <th>First Header</th> - <th>Second Header</th> - </tr> - </thead> - <tbody> - <tr> - <td>Content Cell</td> - <td>Content Cell</td> - </tr> - <tr> - <td>Content Cell</td> - <td>Content Cell</td> - </tr> - </tbody> - </table> - -Usage ------ - -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.tables` -as the name of the extension. - -This extension does not accept any special configuration options. diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.md index 2cd1fa1..a1c583f 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.md @@ -1,8 +1,4 @@ -title: Table of Contents Extension -prev_title: SmartyPants Extension -prev_url: smarty.html -next_title: WikiLinks Extension -next_url: wikilinks.html +title: Table of Contents Extension Table of Contents ================= @@ -18,67 +14,78 @@ This extension is included in the standard Markdown library. Syntax ------ -By default, all headers will automatically have unique `id` attributes +By default, all headers will automatically have unique `id` attributes generated based upon the text of the header. Note this example, in which all three headers would have the same `id`: - #Header - #Header - #Header +```md +#Header +#Header +#Header +``` Results in: - <h1 id="header">Header</h1> - <h1 id="header_1">Header</h1> - <h1 id="header_2">Header</h1> +```html +<h1 id="header">Header</h1> +<h1 id="header_1">Header</h1> +<h1 id="header_2">Header</h1> +``` Place a marker in the document where you would like the Table of Contents to appear. Then, a nested list of all the headers in the document will replace the marker. The marker defaults to `[TOC]` so the following document: - [TOC] +```md +[TOC] - # Header 1 +# Header 1 - ## Header 2 +## Header 2 +``` would generate the following output: - <div class="toc"> +```html +<div class="toc"> + <ul> + <li><a href="#header-1">Header 1</a></li> <ul> - <li><a href="#header-1">Header 1</a></li> - <ul> - <li><a href="#header-2">Header 2</a></li> - </ul> + <li><a href="#header-2">Header 2</a></li> </ul> - </div> - <h1 id="header-1">Header 1</h1> - <h1 id="header-2">Header 2</h1> - -Regardless of whether a `marker` is found in the document (or disabled), the Table of -Contents is available as an attribute (`toc`) on the Markdown class. This allows -one to insert the Table of Contents elsewhere in their page template. For example: - - >>> md = markdown.Markdown(extensions=['markdown.extensions.toc']) - >>> html = md.convert(text) - >>> page = render_some_template(context={'body': html, 'toc': md.toc}) + </ul> +</div> +<h1 id="header-1">Header 1</h1> +<h1 id="header-2">Header 2</h1> +``` + +Regardless of whether a `marker` is found in the document (or disabled), the +Table of Contents is available as an attribute (`toc`) on the Markdown class. +This allows one to insert the Table of Contents elsewhere in their page +template. For example: + +```pycon +>>> md = markdown.Markdown(extensions=['markdown.extensions.toc']) +>>> html = md.convert(text) +>>> page = render_some_template(context={'body': html, 'toc': md.toc}) +``` Usage ----- -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.toc` +See [Extensions](index.md) for general extension usage, specify `markdown.extensions.toc` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The following options are provided to configure the output: * **`marker`**: Text to find and replace with the Table of Contents. Defaults to `[TOC]`. - - Set to an empty string to disable searching for a marker, which may save some time, - especially on long documents. + + Set to an empty string to disable searching for a marker, which may save + some time, especially on long documents. * **`title`**: Title to insert in the Table of Contents' `<div>`. Defaults to `None`. @@ -89,18 +96,20 @@ 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 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. + + 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. * **`baselevel`**: 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 - Markdown text for a page should not contain any headers higher than level 3 - (`<h3>`). The following will accomplish that: + The `baselevel` setting allows the header levels to be automatically + adjusted to 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: + :::pycon >>> text = ''' ... #Some Header ... ## Next Level''' @@ -124,4 +133,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 white space in id. Defaults to "`-`".
\ No newline at end of file + Word separator. Character which replaces white space in id. Defaults to "`-`". diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.md index 948b957..a46265a 100644 --- a/docs/extensions/wikilinks.txt +++ b/docs/extensions/wikilinks.md @@ -1,14 +1,8 @@ -title: WikiLinks Extension -prev_title: Table of Contents Extension -prev_url: toc.html -next_title: Extension API -next_url: api.html +title: WikiLinks Extension -WikiLinks -========= +# WikiLinks -Summary -------- +## Summary The WikiLinks extension adds support for [WikiLinks][]. Specifically, any ``[[bracketed]]`` word is converted to a link. @@ -17,17 +11,20 @@ This extension is included in the standard Markdown library. [WikiLinks]: http://en.wikipedia.org/wiki/Wikilink -Syntax ------- +## Syntax A ``[[bracketed]]`` word is any combination of upper or lower case letters, number, dashes, underscores and spaces surrounded by double brackets. Therefore - [[Bracketed]] +```md +[[Bracketed]] +``` would produce the following HTML: - <a href="/Bracketed/" class="wikilink">Bracketed</a> +```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 @@ -37,19 +34,22 @@ Also note that when a space is used, the space is converted to an underscore in the link but left as-is in the label. Perhaps an example would illustrate this best: - [[Wiki Link]] +```md +[[Wiki Link]] +``` becomes - <a href="/Wiki_Link/" class="wikilink">Wiki Link</a> +```html +<a href="/Wiki_Link/" class="wikilink">Wiki Link</a> +``` -Usage ------ +## Usage -See [Extensions](index.html) for general extension usage, specify `markdown.extensions.wikilinks` -as the name of the extension. +See [Extensions](index.md) for general extension usage, specify +`markdown.extensions.wikilinks` as the name of the extension. -See the [Library Reference](../reference.html#extensions) for information about +See the [Library Reference](../reference.md#extensions) for information about configuring extensions. The default behavior is to point each link to the document root of the current @@ -72,46 +72,55 @@ The following options are provided to change the default behavior: * **`build_url`**: Callable which formats the URL from its parts. -### Examples ### +### Examples 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 - >>> html = markdown.markdown(text, - ... extensions=[WikiLinkExtension(base_url='/wiki/', end_url='.html')] - ... ) +```pycon +>>> from markdown.extensions.wikilinks import WikiLinkExtension +>>> html = markdown.markdown(text, +... extensions=[WikiLinkExtension(base_url='/wiki/', end_url='.html')] +... ) +``` The above would result in the following link for `[[WikiLink]]`. - <a href="/wiki/WikiLink.html" class="wikilink">WikiLink</a> +```html +<a href="/wiki/WikiLink.html" class="wikilink">WikiLink</a> +``` If you want to do more that just alter the base and/or end of the URL, you could also pass in a callable which must accept three arguments (``label``, ``base``, and ``end``). The callable must return the URL in it's entirety. - >>> def my_url_builder(label, base, end): - ... # do stuff - ... return url - ... - >>> html = markdown.markdown(text, - ... extensions=[WikiLinkExtension(build_url=my_url_builder)], - ... ) +```pycon +>>> def my_url_builder(label, base, end): +... # do stuff +... return url +... +>>> html = markdown.markdown(text, +... extensions=[WikiLinkExtension(build_url=my_url_builder)], +... ) +``` The option is also provided to change or remove the class attribute. - >>> html = markdown.markdown(text, - ... extensions=[WikiLinkExtension(html_class='myclass')] - ... ) +```pycon +>>> html = markdown.markdown(text, +... extensions=[WikiLinkExtension(html_class='myclass')] +... ) +``` Would cause all WikiLinks to be assigned to the class `myclass`. - <a href="/WikiLink/" class="myclass">WikiLink</a> +```html +<a href="/WikiLink/" class="myclass">WikiLink</a> +``` -Using with Meta-Data extension ------------------------------- +## Using with Meta-Data extension -The WikiLink extension also supports the [Meta-Data](meta_data.html) extension. +The WikiLink extension also supports the [Meta-Data](meta_data.md) extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are: @@ -124,12 +133,16 @@ When used, the meta-data will override the settings provided through the This document: - wiki_base_url: http://example.com/ - wiki_end_url: .html - wiki_html_class: +```md +wiki_base_url: http://example.com/ +wiki_end_url: .html +wiki_html_class: - A [[WikiLink]] in the first paragraph. +A [[WikiLink]] in the first paragraph. +``` would result in the following output (notice the blank `wiki_html_class`): - <p>A <a href="http://example.com/WikiLink.html">WikiLink</a> in the first paragraph.</p> +```html +<p>A <a href="http://example.com/WikiLink.html">WikiLink</a> in the first paragraph.</p> +``` |