aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2009-03-19 21:35:21 -0400
committerWaylan Limberg <waylan@gmail.com>2009-03-19 21:35:21 -0400
commitc1eb12e10480a60e2fc26a0091cafb779553a4fe (patch)
tree98b0a5cdceb23430c84433f25516796ec3e7ed06
parent70c81659eca814bb037b93c95996210d192e5ca5 (diff)
downloadmarkdown-c1eb12e10480a60e2fc26a0091cafb779553a4fe.tar.gz
markdown-c1eb12e10480a60e2fc26a0091cafb779553a4fe.tar.bz2
markdown-c1eb12e10480a60e2fc26a0091cafb779553a4fe.zip
Added documentation for the rest of the extensions included with the distribution.
-rw-r--r--docs/extensions/CodeHilite.txt113
-rw-r--r--docs/extensions/HTML_Tidy.txt27
-rw-r--r--docs/extensions/ImageLinks.txt27
-rw-r--r--docs/extensions/Meta-Data.txt88
-rw-r--r--docs/extensions/RSS.txt35
-rw-r--r--docs/extensions/Tables_of_Contents.txt50
-rw-r--r--docs/extensions/WikiLinks.txt128
-rw-r--r--docs/extensions/index.txt2
8 files changed, 469 insertions, 1 deletions
diff --git a/docs/extensions/CodeHilite.txt b/docs/extensions/CodeHilite.txt
new file mode 100644
index 0000000..482ad60
--- /dev/null
+++ b/docs/extensions/CodeHilite.txt
@@ -0,0 +1,113 @@
+CodeHilite
+==========
+
+Summary
+-------
+
+The CodeHilite Extension adds code/syntax highlighting to standard
+Python-Markdown code blocks using [Pygments][].
+
+[Python-Markdown]: http://www.freewisdom.org/projects/python-markdown/
+[Pygments]: http://pygments.org/
+
+This extension is included in the Markdown library.
+
+Setup
+-----
+
+You will also need to [download][dl] and install the Pygments package on your
+`PYTHONPATH`. You will need to determine the appropriate CSS classes and create
+appropriate rules for them, which are either defined in or linked from the
+header of your HTML templates. See the excellent [documentation][] for more
+details. If no language is defined, Pygments will attempt to guess the
+language. When that fails, the code block will display as un-highlighted code.
+
+[dl]: http://pygments.org/download/
+[documentation]: http://pygments.org/docs
+
+**Note:** The css and/or javascript is not included as part of this extension
+but shall always be provided by the end user.
+
+Syntax
+------
+
+The CodeHilite Extension follows the same [syntax][] as regular Markdown code
+blocks, with one exception. The hiliter needs to know what language to use for
+the code block. There are three ways to tell the hiliter what language the code
+block contains and each one has a different result.
+
+[syntax]: http://daringfireball.net/projects/markdown/syntax#precode
+
+###SheBang (with path)
+
+If the first line of the codeblock contains a shebang, the language is derived
+from that and line numbers are used.
+
+ #!/usr/bin/python
+ # Code goes here ...
+
+Will result in:
+
+ #!/usr/bin/python
+ # Code goes here ...
+
+
+###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 ...
+
+Will result in:
+
+ # Code goes here ...
+
+####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 ...
+
+Will result in:
+
+ # Code goes here ...
+
+###When No Language is Defined
+
+CodeHilite is completely backward compatible so that if a code block is
+encountered that does not define a language, the block is simple wrapped in
+`<pre>` tags and output. Note: one exception would be that the Pygments
+highlighting engine will try to guess the language. Upon failure, the same
+behavior will happen as described here.
+
+ # Code goes here ...
+
+Will result in:
+
+ # Code goes here ...
+
+Lets see the source for that:
+
+ <div class="codehilite" ><pre><code># Code goes here ...
+ </code></pre></div>
+
+Usage
+-----
+
+From the Python interpreter:
+
+ >>> html = markdown.markdown(text, ['codehilite'])
+
+If you want every code block to have line numbers, even when using colons
+(`:::`) for language identification, the setting `force_linenos` is available
+to do so.
+
+ >>> html = markdown.markdown(text,
+ ... ['codehilite(force_linenos=True)']
+ ... )
diff --git a/docs/extensions/HTML_Tidy.txt b/docs/extensions/HTML_Tidy.txt
new file mode 100644
index 0000000..52f991f
--- /dev/null
+++ b/docs/extensions/HTML_Tidy.txt
@@ -0,0 +1,27 @@
+HTML Tidy
+=========
+
+Runs [HTML Tidy][] on the output of Python-Markdown using the [uTidylib][]
+Python wrapper. Both libtidy and uTidylib must be installed on your system.
+
+This extension is available in the standard Markdown library since version 2.0.
+
+[HTML Tidy]: http://tidy.sourceforge.net/
+[uTidylib]: http://utidylib.berlios.de/
+
+Note than any Tidy [options][] can be passed in as extension configs. So,
+for example, to output HTML rather than XHTML, set ``output_xhtml=0``. To
+indent the output, set ``indent=auto`` and to have Tidy wrap the output in
+``<html>`` and ``<body>`` tags, set ``show_body_only=0``. See Tidy's
+[options][] for a full list of the available options. The defaults are set to
+most closely match Markdowns defaults with the exception that you get much
+better pretty-printing.
+
+[options]: http://tidy.sourceforge.net/docs/quickref.html
+
+Note that options set in this extension will override most any other settings
+passed on to Markdown (such as "output_format"). Unlike Markdown, this extension
+will also treat raw HTML no different than that output by Markdown. In other
+words, it may munge a document authors carefully crafted HTML. Of course, it
+may also transform poorly formed raw HTML into nice, valid HTML. Take these
+things into consideration when electing to use this extension.
diff --git a/docs/extensions/ImageLinks.txt b/docs/extensions/ImageLinks.txt
new file mode 100644
index 0000000..db4f99f
--- /dev/null
+++ b/docs/extensions/ImageLinks.txt
@@ -0,0 +1,27 @@
+ImageLinks
+==========
+
+Summary
+-------
+
+ImageLinks is a Python-Markdown extension that provides a mechanism for
+defining mini-photo galleries within a markdown document.
+
+This extension is part of the Markdown library since 2.0.
+
+Syntax
+------
+
+Turns paragraphs like
+
+ <~~~~~~~~~~~~~~~~~~~~~~~~
+ dir/subdir
+ dir/subdir
+ dir/subdir
+ ~~~~~~~~~~~~~~
+ dir/subdir
+ dir/subdir
+ dir/subdir
+ ~~~~~~~~~~~~~~~~~~~>
+
+Into mini-photo galleries.
diff --git a/docs/extensions/Meta-Data.txt b/docs/extensions/Meta-Data.txt
new file mode 100644
index 0000000..982ea67
--- /dev/null
+++ b/docs/extensions/Meta-Data.txt
@@ -0,0 +1,88 @@
+Meta-Data
+=========
+
+Summary
+-------
+
+An extension to Python-Markdown that adds a syntax for defining meta-data about
+a document. The Meta-Data extension is inspired by and follows the syntax of
+[MultiMarkdown][]. Currently, this extension does not use the meta-data in any
+way, but simply provides it as a `Meta` attribute of a markdown instance for
+use by other extensions or directly by your python code.
+
+[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
+
+This extension has been a part of the Markdown library since 2.0.
+
+Syntax
+------
+
+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
+
+ 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
+anything following the colon on the line and may even be blank. If a line is
+indented 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.
+The first blank line ends all meta-data for the document. Therefore, the first
+line of a document must not be blank. All meta-data is stripped from the
+document prior to any further processing by markdown.
+
+Accessing the Meta-Data
+-----------------------
+
+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 = ['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
+various markdown extensions. The possibilities are left to the imagination of
+the developer.
+
+Compatible Extensions
+---------------------
+
+The following are extensions currently known to work with the Meta-Data
+Extension and the keywords they are known to support:
+
+* [[HeaderId]]
+ * `header_level`
+ * `header_forceid`
+* [[WikiLinks]]
+ * `wiki_base_url`
+ * `wiki_end_url`
+ * `wiki_html_class`
+
diff --git a/docs/extensions/RSS.txt b/docs/extensions/RSS.txt
new file mode 100644
index 0000000..f2ecf0c
--- /dev/null
+++ b/docs/extensions/RSS.txt
@@ -0,0 +1,35 @@
+RSS
+===
+
+Summary
+-------
+
+An extension to Python-Markdown that outputs a markdown document as RSS. 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.
+
+Usage
+-----
+
+From the Python interpreter:
+
+ >>> import markdown
+ >>> text = "Some markdown document."
+ >>> rss = markdown.markdown(text, ['rss'])
+
+Configuring the Output
+----------------------
+
+An RSS document includes some data about the document (URI, author, title) that
+will likely need to be configured for your needs. Therefore, three configuration
+options are available:
+
+* **URL** : The Main URL for the document.
+* **CREATOR** : The Feed creator's name.
+* **TITLE** : The title for the feed.
+
+An example:
+
+ >>> rss = markdown.markdown(text, extensions = \
+ ... ['rss(URL=http://example.com,CREATOR=JOHN DOE,TITLE=My Document)']
+ ... )
diff --git a/docs/extensions/Tables_of_Contents.txt b/docs/extensions/Tables_of_Contents.txt
new file mode 100644
index 0000000..032c25c
--- /dev/null
+++ b/docs/extensions/Tables_of_Contents.txt
@@ -0,0 +1,50 @@
+Table of Contents
+=================
+
+Summary
+-------
+
+Adds a Table of Contents to a Markdown document.
+
+This extension is included with the Markdown library since version 2.0.
+
+Syntax
+------
+
+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]
+
+ # Header 1
+
+ ## Header 2
+
+would generate the following output:
+
+ <div class="toc">
+ <ul>
+ <li><a href="#header-1">Header 1</a></li>
+ <ul>
+ <li><a href="#header-2">Header 2</a></li>
+ </ul>
+ </ul>
+ </div>
+ <h1 id="header-1">Header 1</h1>
+ <h1 id="header-2">Header 2</h1>
+
+Configuration Options
+---------------------
+
+The following options are provided to configure the output:
+
+* **marker**: Text to find and replace with the Table of Contents. Defaults
+ to ``[TOC]``.
+* **slugify**: Callable to generate anchors based on header text. Defaults to a
+ built in ``slugify`` method. The callable must accept one argument which
+ contains the text content of the header and return a string which will be
+ used as the anchor text.
+* **title**: Title to insert in TOC ``<div>``. Defaults to ``None``.
+* **anchorlink**: Set to ``True`` to have the headers link to themselves.
+ Default is ``False``.
diff --git a/docs/extensions/WikiLinks.txt b/docs/extensions/WikiLinks.txt
new file mode 100644
index 0000000..73991cf
--- /dev/null
+++ b/docs/extensions/WikiLinks.txt
@@ -0,0 +1,128 @@
+WikiLinks
+=========
+
+Summary
+-------
+
+An extension to Python-Markdown that adds [WikiLinks][]. Specifically, any
+``[[bracketed]]`` word is converted to a link.
+
+[WikiLinks]: http://en.wikipedia.org/wiki/Wikilink
+
+This extension has been included in the Markdown library since 2.0.
+
+Syntax
+------
+
+A ``[[bracketed]]`` word is any combination of upper or lower case letters,
+number, dashes, underscores and spaces surrounded by double brackets. Therefore
+
+ [[Bracketed]]
+
+Would produce the following html:
+
+ <a href="/Bracketed/" class="wikilink">Bracketed</a>
+
+Note that wikilinks are automatically assigned `class="wikilink"` making it
+easy to style wikilinks differently from other links on a page if one so
+desires. See below for ways to alter the class.
+
+You should 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]]
+
+Becomes
+
+ <a href="/Wiki_Link/" class="wikilink">Wiki Link</a>
+
+Usage
+-----
+
+From the Python interpreter:
+
+ >>> text = "Some text with a [[WikiLink]]."
+ >>> html = markdown.markdown(text, ['wikilink'])
+
+The default behavior is to point each link to the document root of the current
+domain and close with a trailing slash. Additionally, each link is assigned to
+the html class `wikilink`. This may not always be desirable. Therefore, one can
+customize that behavior within Python code. Three settings are provided to
+change the default behavior:
+
+1. **base_url**: String to append to beginning of URL.
+
+ Default: `'/'`
+
+2. **end_url**: String to append to end of URL.
+
+ Default: `'/'`
+
+3. **html_class**: CSS hook. Leave blank for none.
+
+ Default: `'wikilink'`
+
+For an example, let us suppose links should always point to the subdirectory
+`/wiki/` and end with `.html`
+
+ >>> html = markdown.markdown(text,
+ ... ['wikilink(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>
+
+The option is also provided to change or remove the class attribute.
+
+ >>> html = markdown.markdown(text,
+ ... ['wikilink(base_url=myclass)']
+ ... )
+
+Would cause all wikilinks to be assigned to the class `myclass`.
+
+ <a href="/WikiLink/" class="myclass">WikiLink</a>
+
+The same options can be used on the command line as well:
+
+ python markdown.py -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt
+
+Some may prefer the more complex format when calling the `Markdown` class directly:
+
+ >>> md = markdown.Markdown(
+ ... extensions = ['wikilink'],
+ ... extension_configs = {'wikilink': [
+ ... ('base_url', 'http://example.com/'),
+ ... ('end_url', '.html'),
+ ... ('html_class', '') ]},
+ ... safe_mode = True
+ ... )
+ >>> html = md.convert(text)
+
+Using with Meta-Data
+--------------------
+
+The WikiLink Extension also supports the [[Meta-Data]] Extension. Please see
+the documentation for that extension for specifics. The supported meta-data
+keywords are:
+
+* `wiki_base_url`
+* `wiki_end_url`
+* `wiki_html_class`
+
+When used, the meta-data will override the settings provided through the
+`extension_configs` interface.
+
+This document:
+
+ wiki_base_url: http://example.com/
+ wiki_end_url: .html
+ wiki_html_class:
+
+ 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>
+
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 719f513..71d857c 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -22,7 +22,7 @@ available to you.
* [[ImageLinks]]
* [[Meta-Data]]
* [[RSS]]
-* [[Table of Contents]]
+* [[Table_of_Contents]]
* [[WikiLinks]]
Unofficially Supported Extensions