diff options
| -rw-r--r-- | docs/extensions/CodeHilite.txt | 113 | ||||
| -rw-r--r-- | docs/extensions/HTML_Tidy.txt | 27 | ||||
| -rw-r--r-- | docs/extensions/ImageLinks.txt | 27 | ||||
| -rw-r--r-- | docs/extensions/Meta-Data.txt | 88 | ||||
| -rw-r--r-- | docs/extensions/RSS.txt | 35 | ||||
| -rw-r--r-- | docs/extensions/Tables_of_Contents.txt | 50 | ||||
| -rw-r--r-- | docs/extensions/WikiLinks.txt | 128 | ||||
| -rw-r--r-- | docs/extensions/index.txt | 2 |
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 |