aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2009-03-18 23:29:40 -0400
committerWaylan Limberg <waylan@gmail.com>2009-03-18 23:29:40 -0400
commit70c81659eca814bb037b93c95996210d192e5ca5 (patch)
tree20b523620683e1d3efc30c3049e8a3ea2d9a7eb0
parente4508b2a767e0679bca71086890998d5e328517d (diff)
downloadmarkdown-70c81659eca814bb037b93c95996210d192e5ca5.tar.gz
markdown-70c81659eca814bb037b93c95996210d192e5ca5.tar.bz2
markdown-70c81659eca814bb037b93c95996210d192e5ca5.zip
Added documentation for Extra Extension and all the extentions it supports. Still need to do non-extra extensions.
-rw-r--r--docs/extensions/Abbreviations.txt53
-rw-r--r--docs/extensions/Definition_Lists.txt55
-rw-r--r--docs/extensions/Fenced_Code_Blocks.txt63
-rw-r--r--docs/extensions/HeaderId.txt104
-rw-r--r--docs/extensions/Tables.txt53
-rw-r--r--docs/extensions/extra.txt43
-rw-r--r--docs/extensions/footnotes.txt62
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">&lt;p&gt;HTML Document&lt;/p&gt;
+ </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+++)'])
+