aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_template.html2
-rw-r--r--docs/basic.css23
-rw-r--r--docs/change_log.txt10
-rw-r--r--docs/extensions/attr_list.txt2
-rw-r--r--docs/extensions/index.txt75
-rw-r--r--docs/extensions/wikilinks.txt2
-rw-r--r--docs/index.txt67
-rw-r--r--docs/reference.txt64
-rw-r--r--docs/release-2.2.0.txt4
-rw-r--r--docs/release-2.2.1.txt12
-rw-r--r--docs/release-2.3.txt37
11 files changed, 241 insertions, 57 deletions
diff --git a/docs/_template.html b/docs/_template.html
index 202fefb..d3780dd 100644
--- a/docs/_template.html
+++ b/docs/_template.html
@@ -62,7 +62,7 @@
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
- <a href="siteindex.html" title="General Index">index</a></li>
+ <a href="%(base)ssiteindex.html" title="General Index">index</a></li>
<li class="right">
<a href="%(next_url)s" title="%(next_title)s"
accesskey="N">next</a> |</li>
diff --git a/docs/basic.css b/docs/basic.css
index 2b47622..3f7ad80 100644
--- a/docs/basic.css
+++ b/docs/basic.css
@@ -246,18 +246,21 @@ div.body p.centered {
/* -- tables ---------------------------------------------------------------- */
-table.docutils {
+table {
border: 0 solid #dce;
border-collapse: collapse;
}
-table.docutils td, table.docutils th {
+table td, table th {
padding: 2px 5px 2px 5px;
- border-left: 0;
- background-color: #eef;
}
-table.docutils td p.last, table.docutils th p.last {
+table td {
+ border: 1px solid #ddd;
+ background-color: #eef;
+}
+
+table td p.last, table th p.last {
margin-bottom: 0;
}
@@ -269,8 +272,8 @@ table.footnote td, table.footnote th {
border: 0 !important;
}
-table.docutils th {
- border-top: 1px solid #cac;
+table th {
+ border: 1px solid #cac;
background-color: #ede;
}
@@ -280,7 +283,7 @@ th {
}
th.head {
- text-align: center;
+ text-align: center;
}
/* -- other body styles ----------------------------------------------------- */
@@ -371,6 +374,10 @@ pre {
overflow-y: hidden;
}
+code {
+ font-size: 1.1em;
+}
+
td.linenos pre {
padding: 5px 0px;
border: 0;
diff --git a/docs/change_log.txt b/docs/change_log.txt
index 3265aef..ef559e0 100644
--- a/docs/change_log.txt
+++ b/docs/change_log.txt
@@ -1,12 +1,18 @@
title: Change Log
prev_title: Test Suite
prev_url: test_suite.html
-next_title: Release Notes for v2.2.0
-next_url: release-2.2.0.html
+next_title: Release Notes for v2.3
+next_url: release-2.3.html
Python-Markdown Changelog
=========================
+__________: Released version 2.3.0 ([Notes](release-2.3.html))
+
+Nov 4, 2012: Released version 2.2.1 ([Notes](release-2.2.1.html)).
+
+Jul 5, 2012: Released version 2.2.0 ([Notes](release-2.2.0.html)).
+
Jan 22, 2012: Released version 2.1.1 ([Notes](release-2.1.1.html)).
Nov 24, 2011: Released version 2.1.0 ([Notes](release-2.1.0.html)).
diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt
index 11c6a28..4134a82 100644
--- a/docs/extensions/attr_list.txt
+++ b/docs/extensions/attr_list.txt
@@ -73,7 +73,7 @@ The above results in the following output:
To define attributes on inline elements, the attribute list should be defined
immediately after the inline element with no whitespace.
- [link](http://example.com){: class="foo bar" title="Some title! }
+ [link](http://example.com){: class="foo bar" title="Some title!" }
The above results in the following output:
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 610fe21..c9ee005 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -15,12 +15,12 @@ actual source files.
To use an extension, pass it's name to markdown with the `extensions` keyword.
See the [Library Reference](../reference.html#extensions) for more details.
- markdown.markdown(some_text, extensions=['extra', 'nl2br'])
+ markdown.markdown(some_text, extensions=['footnotes', 'nl2br'])
From the command line, specify an extension with the `-x` option. See the
[Command Line docs](../cli.html) or use the `--help` option for more details.
- python -m markdown -x extra input.txt > output.html
+ python -m markdown -x footnotes -x tables input.txt > output.html
Officially Supported Extensions
-------------------------------
@@ -31,24 +31,59 @@ maintained here and all bug reports should be made to the project. If you
have a typical install of Python-Markdown, these extensions are already
available to you.
-* [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)
-* [HTML Tidy](html_tidy.html)
-* [HeaderId](header_id.html)
-* [Meta-Data](meta_data.html)
-* [New Line to Break](nl2br.html)
-* [RSS](rss.html)
-* [Sane Lists](sane_lists.html)
-* [Table of Contents](toc.html)
-* [WikiLinks](wikilinks.html)
+### Markdown Extra
+
+You can enable **all** these extensions just as if it was a single
+`extra` extension. Example:
+
+ markdown.markdown(some_text, extensions=['extra', 'codehilite'])
+
+Extension | Name in Python-Markdown
+--------- | -----------------------
+[Abbreviations][] | `abbr`
+[Attribute Lists][] | `attr_list`
+[Definition Lists][] | `def_list`
+[Fenced Code Blocks][] | `fenced_code`
+[Footnotes][] | `footnotes`
+[Tables][] | `tables`
+[Smart Strong][] | `smart_strong`
+
+[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
+
+### Other extensions
+
+There are also some extensions that are not included in Markdown Extra
+but come in the standard Python-Markdown library.
+
+Extension | Name in Python-Markdown
+--------- | -----------------------
+[Admonition][] | `admonition`
+[CodeHilite][] | `codehilite`
+[HTML Tidy][] | `html_tidy`
+[HeaderId] | `headerid`
+[Meta-Data] | `meta`
+[New Line to Break] | `nl2br`
+[RSS] | `rss`
+[Sane Lists] | `sane_lists`
+[Table of Contents] | `toc`
+[WikiLinks] | `wikilinks`
+
+[Admonition]: admonition.html
+[CodeHilite]: code_hilite.html
+[HTML Tidy]: html_tidy.html
+[HeaderId]: header_id.html
+[Meta-Data]: meta_data.html
+[New Line to Break]: nl2br.html
+[RSS]: rss.html
+[Sane Lists]: sane_lists.html
+[Table of Contents]: toc.html
+[WikiLinks]: wikilinks.html
Third Party Extensions
----------------------
diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt
index b5e2b04..5f6d20e 100644
--- a/docs/extensions/wikilinks.txt
+++ b/docs/extensions/wikilinks.txt
@@ -99,7 +99,7 @@ could also pass in a callable which must accept three arguments (``label``,
The option is also provided to change or remove the class attribute.
>>> html = markdown.markdown(text,
- ... ['wikilink(base_url=myclass)']
+ ... ['wikilink(html_class=myclass)']
... )
Would cause all wikilinks to be assigned to the class `myclass`.
diff --git a/docs/index.txt b/docs/index.txt
index eb245e6..b44f5ae 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -9,12 +9,26 @@ Python-Markdown
This is a Python implementation of John Gruber's
[Markdown](http://daringfireball.net/projects/markdown/).
It is almost completely compliant with the reference implementation,
-though there are a few very minor differences. See John's
+though there are a few very minor [differences](#differences). See John's
[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax)
for the syntax rules.
See the [installation instructions](install.html) to get started.
+Goals
+-----
+
+The Python-Markdown project is developed with the following goals in mind:
+
+* Maintain a Python 2 *and* Python 3 library (with an optional CLI wrapper)
+ suited to use in web server environments (never raise an exception, never
+ write to stdout, etc.) as an implementation of the markdown parser that
+ follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax)
+ and the behavior of the original (markdown.pl) implementation as reasonably
+ as possible (see [differences](#differences) for a few exceptions).
+* Provide an [Extension API](extensions/api.html) which allows any behaviors of
+ the parser to be overridden/changed/added.
+
Features
--------
@@ -27,13 +41,6 @@ features:
supported by Unicode including bi-directional text. In fact the test suite
includes documents written in Russian and Arabic.
-* __Middle-Word Emphasis__
-
- Python-Markdown defaults to ignoring middle-word emphasis. In other words,
- `some_long_filename.txt` will not become `some<em>long</em>filename.txt`.
- This can be switched off if desired. See the
- [Library Reference](reference.html#smart_emphasis) for details.
-
* __Extensions__
Various [extensions](extensions/index.html) are provided (including
@@ -58,6 +65,50 @@ features:
In addition to being a Python Library, a
[command line script](cli.html) is available for your convenience.
+Differences
+-----------
+
+While Python-Markdown strives to fully implement markdown as described in the
+[syntax rules](http://daringfireball.net/projects/markdown/syntax), the rules
+can be interpreted in different ways and different implementations
+occasionally vary in their behavior (see the
+[Babelmark FAQ](http://johnmacfarlane.net/babelmark2/faq.html#what-are-some-examples-of-interesting-divergences-between-implementations)
+for some examples). Known and intentional differences found in Python-Markdown
+are summarized below:
+
+* __Middle-Word Emphasis__
+
+ Python-Markdown defaults to ignoring middle-word emphasis. In other words,
+ `some_long_filename.txt` will not become `some<em>long</em>filename.txt`.
+ This can be switched off if desired. See the
+ [Library Reference](reference.html#smart_emphasis) for details.
+
+* __Indentation/Tab Length__
+
+ The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list)
+ clearly state that when a list item consists of multiple paragraphs, "each
+ subsequent paragraph in a list item **must** be indented by either 4 spaces
+ or one tab" (emphasis added). However, many implementations do not enforce
+ this rule and allow less than 4 spaces of indentation. The implementers of
+ Python-Markdown consider it a bug to not enforce this rule, and therefore,
+ subsequent paragraphs of a list **must** be indented by four spaces or one
+ tab.
+
+ In the event that one would prefer different behavior,
+ [tab_length](reference.html#tab_length) can be set to whatever length is
+ desired. Be warned however, as this will affect indentation for all aspects
+ of the syntax (including code blocks).
+
+* __Consecutive Lists__
+
+ While the syntax rules are not clear on this, many implementations (including
+ the original) do not end one list and start a second list when the list marker
+ (asterisks, pluses, hyphens, and numbers) changes. For consistency,
+ Python-Markdown maintains the same behavior with no plans to change in the
+ foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.html)
+ is available to provide a less surprising behavior.
+
+
Support
-------
diff --git a/docs/reference.txt b/docs/reference.txt
index bd837ff..8117e69 100644
--- a/docs/reference.txt
+++ b/docs/reference.txt
@@ -55,24 +55,60 @@ The following options are available on the `markdown.markdown` function:
* __`extensions`__{: #extensions }: A list of extensions.
- Python-Markdown provides an API for third parties to write extensions to
- the parser adding their own additions or changes to the syntax. A few
- commonly used extensions are shipped with the markdown library. See
- the [extension documentation](extensions/index.html) for a list of
- available extensions.
-
- The list of extensions may contain instances of extensions or strings of
- extension names. If an extension name is provided as a string, the
- extension must be importable as a python module either within the
- `markdown.extensions` package or on your PYTHONPATH with a name starting
- with `mdx_`, followed by the name of the extension. Thus,
- `extensions=['extra']` will first look for the module
- `markdown.extensions.extra`, then a module named `mdx_extra`.
+ Python-Markdown provides an [API](extensions/api.html) for third parties to
+ write extensions to the parser adding their own additions or changes to the
+ syntax. A few commonly used extensions are shipped with the markdown
+ library. See the [extension documentation](extensions/index.html) for a
+ list of available extensions.
+
+ The list of extensions may contain instances of extensions and/or strings
+ of extension names.
+
+ extensions=[MyExtension(), 'path.to.my.ext', 'extra']
+
+ When passing in extension instances, each class instance must be a subclass
+ of `markdown.extensions.Extension` and any configuration options should be
+ defined when initiating the class instance rather than using the
+ [extension_configs](#extension_configs) keyword. For example:
+
+ from markdown.extensions import Extension
+ class MyExtension(Extension):
+ # define your extension here...
+
+ markdown.markdown(text, extensions=[MyExtension(configs={'option': 'value'}))
+
+ If an extension name is provided as a string, the extension must be
+ importable as a python module on your PYTHONPATH. Python's dot notation is
+ supported. Therefore, to import the 'extra' extension, one could do
+ `extensions=['markdown.extensions.extra']` However, if no dots are provided
+ in the string (`extensions=['extra']`) Markdown will first look for the
+ module `markdown.extensions.extra` (the built-in extension), then a module
+ named `mdx_extra` ('mdx_' will be appended to the beginning of the string)
+ at the root of your PYTHONPATH.
+
+ When loading an extension by name (as a sting), you may either pass in
+ configuration settings to the extension using the
+ [extension_configs](#extension_configs) keyword or by appending the
+ settings to the name in the following format:
+
+ extensions=['name(option1=value,option2=value)']
+
+ Note that there are no quotes or whitespace in the above format, which
+ severely limits how it can be used. For more complex settings, it is
+ suggested that the [extension_configs](#extension_configs) keyword
+ be used or an instance of a class be passed in.
+
+ See the documentation of the [Extension API](extensions/api.html) for
+ assistance in creating extensions.
* __`extension_configs`__{: #extension_configs }: A dictionary of
configuration settings for extensions.
- The dictionary must be of the following format:
+ Any configuration settings will only be passed to extensions loaded by name
+ (as a string). When loading extensions as class instances, pass the
+ configuration settings directly to the class when initializing it.
+
+ The dictionary of configuration settings must be in the following format:
extension_configs = {'extension_name_1':
[
diff --git a/docs/release-2.2.0.txt b/docs/release-2.2.0.txt
index d7081eb..59ac78f 100644
--- a/docs/release-2.2.0.txt
+++ b/docs/release-2.2.0.txt
@@ -1,6 +1,6 @@
title: Release Notes for v2.2.0
-prev_title: Change Log
-prev_url: change_log.html
+prev_title: Release Notes for v2.2.1
+prev_url: release-2.2.1.html
next_title: Release Notes for v2.1.1
next_url: release-2.1.1.html
diff --git a/docs/release-2.2.1.txt b/docs/release-2.2.1.txt
new file mode 100644
index 0000000..fe27c71
--- /dev/null
+++ b/docs/release-2.2.1.txt
@@ -0,0 +1,12 @@
+title: Release Notes for v2.2.1
+prev_title: Release Notes for v2.3
+prev_url: release-2.3.html
+next_title: Release Notes for v2.2.0
+next_url: release-2.2.0.html
+
+Python-Markdown 2.2.1 Release Notes
+===================================
+
+Python-Markdown 2.2.1 is a bug-fix release. No new features have been added.
+However, at least one bug fix does not work in Python 2.4 so that version of
+Python is no longer supported. For a full list of changes, see the git log.
diff --git a/docs/release-2.3.txt b/docs/release-2.3.txt
new file mode 100644
index 0000000..9c53d12
--- /dev/null
+++ b/docs/release-2.3.txt
@@ -0,0 +1,37 @@
+title: Release Notes for v2.3
+prev_title: Change Log
+prev_url: change_log.html
+next_title: Release Notes for v2.2.1
+next_url: release-2.2.1.html
+
+Python-Markdown 2.3 Release Notes
+=================================
+
+We are pleased to release Python-Markdown 2.3 which ...
+
+Python-Markdown supports Python versions 2.6, 2.7, 3.1, 3.3, and 3.3.
+
+Backwards-incompatible Changes
+------------------------------
+
+* Support has been dropped for Python 2.5. No guarantees are made that the
+library will work in any version of Python lower than 2.6.
+
+* "safe_mode" has been further restricted. Markdown formated links must be
+of a known whitelisted scheme when in "safe_mode" or the url is discarded.
+The whitelesited schemes are: 'http', 'https', 'ftp', 'ftps', 'mailto',
+'news'. Schemeless urls are also permitted, but are checked in other ways -
+as they have been for some time.
+
+* The ids assigned to footnotes now contain a dash (`-`) rather than a colon
+(`:`) when `output_format` it set to "html5" or "xhtml5". If you are making
+reference to those ids in your JavaScript or CSS and using the HTML5 output,
+you will need to update your code accordingly. No changes are necessary if
+you are outputing XHTML (the default) or HTML4.
+
+What's New in Python-Markdown 2.3
+---------------------------------
+
+Various bug fixes have been made. See the
+[commit log](https://github.com/waylan/Python-Markdown/commits/master)
+for a complete history of the changes.
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-03 02:17:36 +0000