diff options
| -rw-r--r-- | docs/extensions/Abbreviations.txt | 53 | ||||
| -rw-r--r-- | docs/extensions/Definition_Lists.txt | 55 | ||||
| -rw-r--r-- | docs/extensions/Fenced_Code_Blocks.txt | 63 | ||||
| -rw-r--r-- | docs/extensions/HeaderId.txt | 104 | ||||
| -rw-r--r-- | docs/extensions/Tables.txt | 53 | ||||
| -rw-r--r-- | docs/extensions/extra.txt | 43 | ||||
| -rw-r--r-- | docs/extensions/footnotes.txt | 62 |
7 files changed, 433 insertions, 0 deletions
diff --git a/docs/extensions/Abbreviations.txt b/docs/extensions/Abbreviations.txt new file mode 100644 index 0000000..fa54d3c --- /dev/null +++ b/docs/extensions/Abbreviations.txt @@ -0,0 +1,53 @@ +Abbreviations +------------- + +Summary +------- + +The Markdown Abbreviation Extension adds the ability to define abbreviations. +Specifically, any defined abbreviation is wrapped in an `<abbr>` tag. + +The Abbreviation 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 like so: + + <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 +----- + +From the Python interpreter: + + >>> import markdown + >>> text = """ + ... Some text with an ABBR. + ... + ... *[ABBR]: Abbreviation + ... """ + >>> html = markdown.markdown(text, ['abbr']) + +To use with other extensions, just add them to the list, like this: + + >>> html = markdown.markdown(text, ['abbr', 'footnotes']) + +Abbreviations can also be called from the command line using Markdown's `-x` +parameter, like so: + + markdown.py -x abbr source.txt > output.html diff --git a/docs/extensions/Definition_Lists.txt b/docs/extensions/Definition_Lists.txt new file mode 100644 index 0000000..983070d --- /dev/null +++ b/docs/extensions/Definition_Lists.txt @@ -0,0 +1,55 @@ +Definition Lists +---------------- + +Summary +------- + +The Definition List Extension adds the ability to create definition list 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 like so: + + <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 +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['def_list']) + +To use with other extensions, just add them to the list, like this: + + >>> html = markdown.markdown(text, ['def_list', 'footnotes']) + +The extension can also be called from the command line using Markdown's `-x` +parameter: + + markdown.py -x def_list source.txt > output.html diff --git a/docs/extensions/Fenced_Code_Blocks.txt b/docs/extensions/Fenced_Code_Blocks.txt new file mode 100644 index 0000000..6b1ba76 --- /dev/null +++ b/docs/extensions/Fenced_Code_Blocks.txt @@ -0,0 +1,63 @@ +Fenced Code Blocks +================== + +Summary +------- + +This 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 +------ + +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: + + ~~~~~~~~~~~~~~~~~~~~ + a one-line code block + ~~~~~~~~~~~~~~~~~~~~ + +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. + +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 + ~~~~ + + ~~~~.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> + +Usage +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['fenced_code']) + + + diff --git a/docs/extensions/HeaderId.txt b/docs/extensions/HeaderId.txt new file mode 100644 index 0000000..efd1eb8 --- /dev/null +++ b/docs/extensions/HeaderId.txt @@ -0,0 +1,104 @@ +HeaderId +======== + +Summary +------- + +An extension to Python-Markdown that adds an 'id' attribute to HTML header +elements (h1-h6) in markdown's output. + +This extension is included in the standard Markdown library. + +Syntax +------ + +The basic syntax follows [PHP Markdown Extra][]'s implementation: + +[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#header-id + + Header 1 {#header1} + ======== + + ## Header 2 ## {#header2} + +will result in the following HTML: + + <h1 id="header1">Header 1</h1> + + <h2 id="header2">Header 2</h2> + +However, there is much more that this extension does. + +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 + #Another Header {#header} + #Header + +Results in: + + <h1 id="header">Header</h1> + <h1 id="header_1">Another Header</h1> + <h1 id="header_2">Third Header</h1> + +Configuring the Output +---------------------- + +The HeaderId extension has two configuration settings: + +* **level**: Base level for headers. + + Default: `1` + +* **forceid**: Force all headers to have an id. + + Default: `True` + +The `level` setting allows you to automatically adjust the header levels to fit +within the hierarchy of your html templates. For example, the markdown text for +this page should not contain any headers higher than level 3 (`<h3>`). +Therefore, do the following: + + >>> text = ''' + ... #Some Header + ... ## Next Level''' + >>> html = markdown.markdown(text, ['headerid(level=3)']) + >>> print html + <h3 id="some_header">Some Header</h3> + <h4 id="next_level">Next Level</h4>' + +The `forceid` setting turns on or off the automatically generated ids for +headers that do not have one explicitly defined. + + >>> text = ''' + ... # Some Header + ... # Header with ID # { #foo }''' + >>> html = markdown.markdown(text, ['headerid(forceid=False)']) + >>> print html + <h1>Some Header</h1> + <h1 id="foo">Header with ID</h1> + +Using with Meta-Data +-------------------- + +The HeaderId Extension also supports the [[Meta-Data]] 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. + +This document: + + header_level: 2 + header_forceid: Off + + # A Header + + +Will result in the following output: + + <h2>A Header</h2> diff --git a/docs/extensions/Tables.txt b/docs/extensions/Tables.txt new file mode 100644 index 0000000..63d6849 --- /dev/null +++ b/docs/extensions/Tables.txt @@ -0,0 +1,53 @@ +Tables +---------------- + +Summary +------- + +The Table 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 +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['tables']) + diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt new file mode 100644 index 0000000..817d58f --- /dev/null +++ b/docs/extensions/extra.txt @@ -0,0 +1,43 @@ +Python-Markdown Extra +===================== + +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]] +* [[Definition_Lists]] +* [[Fenced_Code_Blocks]] +* [[Footnotes]] +* [[HeaderId]] +* [[Tables]] + +See each individual extension for syntax documentation. Extra and all it's +supported extensions are included in the standard Markdown library. + +Usage +----- + +From the Python interpreter: + + >>> import markdown + >>> html = markdown.markdown(text, ['extra']) + +In the unlikely event that one or more of the supported extensions are not +available for import, Markdown will simply continue without that +extension. If you would like to be notified of such failures, +you may set Python-Markdown's logger level to "WARN". + +There may be additional extensions that are distributed with +Python-Markdown that are not included here in Extra. 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 [[Writing Extensions]]). You could also +edit the `extensions` global variable defined in the source, but be +aware that such changes may be lost when you upgrade to any future +version of Python-Markdown. diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt new file mode 100644 index 0000000..7188f44 --- /dev/null +++ b/docs/extensions/footnotes.txt @@ -0,0 +1,62 @@ +Footnotes +========= + +Summary +------- + +An extension to Python-Markdown that adds footnote syntax. This extension has +been included with Python-Markdown since 1.7 and should be available to anyone +who has a typical install of Python-Markdown. + +Syntax +------ + +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 +the output. + +[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#footnotes + +Example: + + Footnotes[^1] have a label[^label] and a definition[^!DEF]. + + [^1]: This is a footnote + [^label]: A footnote on "label" + [^!DEF]: The definition of a footnote. + +A footnote definition may contain multiple lines, paragraphs, code blocks, +blockquotes and most any other markdown syntax. The additional line simply +must be indented at least an additional four spaces. + + [^1]: The first paragraph of the definition. + + Paragraph two of the definition. + + > A blockquote with + > multiple lines. + + a code block + + A final paragraph. + +By default, the footnote definitions are placed at the end of the resulting +HTML document. However, you may want the footnotes in another location within +the document. Simply place the following text at that location within your +markdown document (See how to configure this text below): + + ///Footnotes Go Here/// + +Usage +----- + +From the Python interpreter: + + >>> html = markdown.markdown(text, ['footnotes']) + +To configure the place marker for footnote definitions (just be sure not to +use any existing markdown syntax): + + >>> html = markdown.markdown(text, ['footnotes(PLACE_MARKER=+++my marker+++)']) + |