Merge pull request #288 from lahwaacz/master

docs: improved documentation

19 files changed, 319 insertions, 305 deletions

diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.txt
index 21d90bf..070bb01 100644
--- a/docs/extensions/abbreviations.txt
+++ b/docs/extensions/abbreviations.txt
@@ -1,7 +1,7 @@
-title:      Abbreviation Extension
+title:      Abbreviations Extension
 prev_title: Extra Extension
 prev_url:   extra.html
-next_title: Attribute List Extension
+next_title: Attribute Lists Extension
 next_url:   attr_list.html
 
 Abbreviations
@@ -10,10 +10,10 @@ Abbreviations
 Summary
 -------
 
-The Markdown Abbreviation Extension adds the ability to define abbreviations. 
+The Abbreviations 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.
+The Abbreviations extension is included in the standard Markdown library.
 
 Syntax
 ------
@@ -31,7 +31,7 @@ Thus, the following text (taken from the above referenced PHP documentation):
     *[HTML]: Hyper Text Markup Language
     *[W3C]:  World Wide Web Consortium
 
-will be rendered like so:
+will be rendered as:
 
     <p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification 
     is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>
@@ -39,21 +39,7 @@ will be rendered like so:
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](index.html) for general extension usage, specify `abbr`
+as the name of the extension.
 
-    >>> 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:
-
-    python -m markdown -x abbr source.txt > output.html
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.txt
index 61d410b..088b1fb 100644
--- a/docs/extensions/admonition.txt
+++ b/docs/extensions/admonition.txt
@@ -1,4 +1,4 @@
-title:      Admonition
+title:      Admonition Extension
 prev_title: Smart Strong Extension
 prev_url:   smart_strong.html
 next_title: CodeHilite Extension
@@ -10,7 +10,7 @@ Admonition
 Summary
 -------
 
-This extension adds [rST-style][rST] admonitions to Markdown documents.
+The Admonition extension adds [rST-style][rST] admonitions to Markdown documents.
 
 This extension is included in the standard Markdown library.
 
diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index ef256b8..715df6d 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -1,5 +1,5 @@
 title:      Extensions API
-prev_title: Wikilinks Extension
+prev_title: WikiLinks Extension
 prev_url:   wikilinks.html
 next_title: Test Suite
 next_url:   ../test_suite.html
diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt
index 54a61d0..818fe53 100644
--- a/docs/extensions/attr_list.txt
+++ b/docs/extensions/attr_list.txt
@@ -1,7 +1,7 @@
-title:      Attribute List Extension
-prev_title: Abbreviation Extension
+title:      Attribute Lists Extension
+prev_title: Abbreviations Extension
 prev_url:   abbreviations.html
-next_title: Definition List Extension
+next_title: Definition Lists Extension
 next_url:   definition_lists.html
 
 Attribute Lists
@@ -10,15 +10,15 @@ Attribute Lists
 Summary
 -------
 
-An extension to Python-Markdown that adds a syntax to define attributes on
-the various HTML elements in markdown's output.
+The Attribute Lists extension adds a syntax to define attributes on the various
+HTML elements in markdown's output.
 
 This extension is included in the standard Markdown library.
 
 Syntax
 ------
 
-The basic syntax was inspired by [Maruku][]'s Attribute List feature.
+The basic syntax was inspired by [Maruku][]'s Attribute Lists feature.
 
 [Maruku]: http://maruku.rubyforge.org/proposal.html#attribute_lists
 
@@ -78,3 +78,11 @@ immediately after the inline element with no whitespace.
 The above results in the following output:
 
     <p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p>
+
+Usage
+-----
+
+See [Extensions](index.html) for general extension usage, specify `attr_list`
+as the name of the extension.
+
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
index 92f60f8..2cdb123 100644
--- a/docs/extensions/code_hilite.txt
+++ b/docs/extensions/code_hilite.txt
@@ -10,12 +10,12 @@ CodeHilite
 Summary
 -------
 
-The CodeHilite Extension adds code/syntax highlighting to standard
+The CodeHilite extension adds code/syntax highlighting to standard
 Python-Markdown code blocks using [Pygments][].
 
 [Pygments]: http://pygments.org/
 
-This extension is included in the  Markdown library.
+This extension is included in the standard Markdown library.
 
 Setup
 -----
@@ -37,7 +37,7 @@ language. When that fails, the code block will display as un-highlighted code.
 Syntax
 ------
 
-The CodeHilite Extension follows the same [syntax][] as regular Markdown code
+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.
@@ -51,111 +51,116 @@ block contains and each one has a different result.
 
 [syntax]: http://daringfireball.net/projects/markdown/syntax#precode
 
-* ###SheBang (with path)
+### 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:
+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:
 
-* ###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.
+    #!/usr/bin/python
+    # Code goes here ...
 
-            #!python
-            # Code goes here ...
+### SheBang (no path) ###
 
-    Will result in:
+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 ...
 
-* ###Colons
+Will result in:
 
-    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.
+    # Code goes here ...
 
-            :::python
-            # Code goes here ...
+### Colons ###
 
-    Will result in:
+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 ...
 
-    Certain lines can be selected for emphasis with the colon syntax. By
-    default, emphasized lines have a yellow background. This is useful to
-    direct the reader's attention.
+Will result in:
 
-        :::python hl_lines="1 3"
-        # This line is emphasized
-        # This line isn't
-        # This line is emphasized
+    # Code goes here ...
 
-    (`hl_lines` is named for Pygments' "highlighted lines" option.)
+Certain lines can be selected for emphasis with the colon syntax. By
+default, emphasized lines have a yellow background. This is useful to
+direct the reader's attention.
 
-* ###When No Language is Defined
+    :::python hl_lines="1 3"
+    # This line is emphasized
+    # This line isn't
+    # This line is emphasized
 
-    CodeHilite is completely backward compatible so that if a code block is
-    encountered that does not define a language, the block is simply wrapped in
-    `<pre>` tags and output. 
+!!! Note
+    `hl_lines` is named for Pygments' option meaning "highlighted lines".
 
-            # Code goes here ...
+### When No Language is Defined ###
 
-    Will result in:
+CodeHilite is completely backwards compatible so that if a code block is
+encountered that does not define a language, the block is simply wrapped in
+`<pre>` tags and output. 
 
         # Code goes here ...
 
-    Lets see the source for that:
+Will result in:
 
-        <div class="codehilite"><pre><code># Code goes here ...
-        </code></pre></div>
+    # Code goes here ...
 
-    !!! Note
-        When no language is defined, the Pygments highlighting engine will try to guess 
-        the language (unless `guess_lang` is set to `False`). Upon failure, the same 
-        behavior will happen as described above.
+Lets see the source for that:
+
+    <div class="codehilite"><pre><code># Code goes here ...
+    </code></pre></div>
+
+!!! Note
+    When no language is defined, the Pygments highlighting engine will try to guess 
+    the language (unless `guess_lang` is set to `False`). Upon failure, the same 
+    behavior will happen as described above.
 
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](index.html) for general extension usage, specify `codehilite`
+as the name of the extension.
 
-    >>> html = markdown.markdown(text, extensions=['codehilite'])
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
 
-To force every code block to have line numbers, even when using 
-colons (`:::`) for language identification, set `linenums` to `True`.
+The following options are provided to configure the output:
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['codehilite(linenums=True)']
-    ... )
+* **linenums**:
+    Use line numbers. Possible values are `True` for yes, `False` for no and
+    `None` for auto. Defaults to `None`.
 
-To turn off all line numbers, even when using SheBangs (`#!`) for 
-language identification, set `linenums` to `False`.
+    Using `True` will force every code block to have line numbers, even when
+    using colons (`:::`) for language identification.
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['codehilite(linenums=False)']
-    ... )
+    Using `False` will turn off all line numbers, even when using SheBangs
+    (`#!`) for language identification.
 
-To prevent Pygments from guessing the language (only highlighting
-blocks when you explicitly request it) set the `guess_lang` setting to `False`.
+* **guess_lang**:
+    Automatic language detection. Defaults to `True`.
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['codehilite(guess_lang=False)']
-    ... )
+    Using `False` will prevent Pygments from guessing the language, and thus
+    highlighting blocks only when you explicitly set the language.
 
-To assign a CSS class differant than the default ('codehilite') on the
-code's wrapping div, define a custom class with the `css_class` setting.
+* **css_class**:
+    Set CSS class name for the wrapper `<div>` tag. Defaults to
+    `codehilite`.
 
-    >>> html = markdown.markdown(text,
-    ...    extensions=['codehilite(css_class=myclass)']
-    ... )
+* **pygments_style**:
+    Pygments HTML Formatter Style (ColorScheme). Defaults to `default`.
+
+    !!! Note
+        This is useful only when `noclasses` is set to `True`, otherwise the
+        CSS style shall be provided by the end user.
 
+* **noclasses**:
+    Use inline styles instead of CSS classes. Defaults to `False`.
diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.txt
index a5ba393..31e8601 100644
--- a/docs/extensions/definition_lists.txt
+++ b/docs/extensions/definition_lists.txt
@@ -1,7 +1,7 @@
-title:      Definition List Extension
-prev_title: Attribute List Extension
+title:      Definition Lists Extension
+prev_title: Attribute Lists Extension
 prev_url:   attr_list.html
-next_title: Fenced Code Block Extension
+next_title: Fenced Code Blocks Extension
 next_url:   fenced_code_blocks.html
 
 Definition Lists
@@ -10,7 +10,7 @@ Definition Lists
 Summary
 -------
 
-The Definition List Extension adds the ability to create definition lists in
+The Definition Lists extension adds the ability to create definition lists in
 Markdown documents.
 
 This extension is included in the standard Markdown library.
@@ -32,7 +32,7 @@ Thus, the following text (taken from the above referenced PHP documentation):
     Orange
     :   The fruit of an evergreen tree of the genus Citrus.
 
-will be rendered like so:
+will be rendered as:
 
     <dl>
     <dt>Apple</dt>
@@ -47,15 +47,7 @@ will be rendered like so:
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](index.html) for general extension usage, specify `def_list`
+as the name of the extension.
 
-    >>> 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:
-
-    python -m markdown -x def_list source.txt > output.html
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt
index ace7a57..b90d1b0 100644
--- a/docs/extensions/extra.txt
+++ b/docs/extensions/extra.txt
@@ -1,7 +1,7 @@
 title:      Extra Extension
 prev_title: Extensions
 prev_url:   index.html
-next_title: Abreviation Extension
+next_title: Abreviations Extension
 next_url:   abbreviations.html
 
 Python-Markdown Extra
diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.txt
index 0148c80..206f6da 100644
--- a/docs/extensions/fenced_code_blocks.txt
+++ b/docs/extensions/fenced_code_blocks.txt
@@ -1,5 +1,5 @@
-title:      Fenced Code Block Extension
-prev_title: Definition List Extension
+title:      Fenced Code Blocks Extension
+prev_title: Definition Lists Extension
 prev_url:   definition_lists.html
 next_title: Footnotes Extension
 next_url:   footnotes.html
@@ -10,8 +10,8 @@ Fenced Code Blocks
 Summary
 -------
 
-This extension adds a secondary way to define code blocks which overcomes a few
-limitations of the indented code blocks.
+The Fenced Code Blocks 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.
 
@@ -35,7 +35,7 @@ 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.
 
-### Language
+### Language ###
 
 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 
@@ -60,7 +60,7 @@ The above will output:
     <pre><code class="html">&lt;p&gt;HTML Document&lt;/p&gt;
     </code></pre>
 
-[Github][]'s tilde (`\``) syntax is also supported:
+[Github][]'s backtick (`\``) syntax is also supported:
 
     ```python
     # more python code
@@ -68,17 +68,23 @@ The above will output:
 
 [Github]: http://github.github.com/github-flavored-markdown/
 
-### Emphasized Lines
+### Emphasized Lines ###
 
-If [Pygments][] is installed, this extension can emphasize certain lines of
-code. By default, emphasized lines have a yellow background. This is useful to
-direct the reader's attention. The lines can be specified with PHP Extra's
-syntax:
+If you would like to have your fenced code blocks highlighted with the 
+[CodeHilite][] extension, simply enable that extension (remember that
+[Pygments][] is its dependency) and the language of your fenced code blocks
+will be passed in and highlighted appropriately.
+
+Similar to the [colon][] syntax of the CodeHilite extension, fenced code blocks
+can also have emphasized certain lines of code.
+
+The lines can be specified with PHP Extra's syntax:
 
     ~~~~{.python hl_lines="1 3"}
     # This line is emphasized
     # This line isn't
     # This line is emphasized
+    ~~~~
 
 ... or with GitHub's:
 
@@ -86,22 +92,16 @@ syntax:
     # This line is emphasized
     # This line isn't
     # This line is emphasized
+    ```
 
-(`hl_lines` is named for Pygments' "highlighted lines" option.)
-
+[CodeHilite]: code_hilite.html
 [Pygments]: http://pygments.org/
+[colon]: code_hilite.html#colons
 
 Usage
 -----
 
-From the Python interpreter:
-
-    >>> html = markdown.markdown(text, ['fenced_code'])
-
-If you would like to have your fenced code blocks highlighted with the 
-[CodeHilite][] extension, simply include that extension and the language 
-of your fenced code blocks will be passed in and highlighted appropriately.
-
-    >>> html = markdown.markdown(text, ['fenced_code', 'codehilite'])
+See [Extensions](index.html) for general extension usage, specify `fenced_code`
+as the name of the extension.
 
-[CodeHilite]: code_hilite.html
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt
index e06344b..a18fb06 100644
--- a/docs/extensions/footnotes.txt
+++ b/docs/extensions/footnotes.txt
@@ -1,5 +1,5 @@
 title:      Footnotes Extension
-prev_title: Fenced Code Block Extension
+prev_title: Fenced Code Blocks Extension
 prev_url:   fenced_code_blocks.html
 next_title: Tables Extension
 next_url:   tables.html
@@ -10,9 +10,10 @@ 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.
+The Footnotes extension adds syntax for defining footnotes in Markdown
+documents.
+
+This extension is included in the standard Markdown library.
 
 Syntax
 ------
@@ -28,14 +29,14 @@ Example:
 
     Footnotes[^1] have a label[^@#$%] and the footnote's content.
 
-    [^1]: This is a footnote's content.
+    [^1]: This is a footnote content.
     [^@#$%]: A footnote on the label: "@#$%".
 
 A footnote label must start with a caret `^` and may contain any inline text 
 (including spaces) between a set of square brackets `[]`. Only the first
 caret has any special meaning.
 
-A footnote's content must start with the label followed by a colon and at least 
+A footnote content must start with the label followed by a colon and at least 
 one space. The label used to define the content must exactly match the label used
 in the body (including capitalization and whitespace). The content would then 
 follow the label either on the same line or on the next line. The content may 
@@ -47,7 +48,6 @@ When working with multiple blocks, it may be helpful to start the content on a
 separate line from the label which defines the content. This way the entire block 
 is indented consistently and any errors are more easily discernible by the author.
 
-
     [^1]: 
         The first paragraph of the definition.
 
@@ -60,22 +60,29 @@ is indented consistently and any errors are more easily discernible by the autho
 
         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:
+See [Extensions](index.html) for general extension usage, specify `footnotes`
+as the name of the extension.
+
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
 
-    >>> html = markdown.markdown(text, ['footnotes'])
+The following options are provided to configure the output:
 
-To configure the place marker for footnote definitions (just be sure not to 
-use any existing markdown syntax):
+* **PLACE_MARKER**:
+    A text string used to mark the position where the footnotes are rendered.
+    Defaults to `///Footnotes Go Here///`.
 
-    >>> html = markdown.markdown(text, ['footnotes(PLACE_MARKER=+++my marker+++)'])
+    If the place marker text is not found in the document, the footnote
+    definitions are placed at the end of the resulting HTML document.
 
+* **UNIQUE_IDS**:
+    Whether to avoid collisions across multiple calls to `reset()`. Defaults to
+    `False`.
+    
+* **BACKLINK_TEXT**:
+    The text string that links from the footnote definition back to the position
+    in the document. Defaults to `&#8617;`.
diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.txt
index c1739a0..afa1fe1 100644
--- a/docs/extensions/header_id.txt
+++ b/docs/extensions/header_id.txt
@@ -10,17 +10,17 @@ HeaderId
 Summary
 -------
 
-An extension to Python-Markdown that automatically generates 'id' attributes
-for HTML header elements (h1-h6) in markdown's output.
+The HeaderId extension automatically generates `id` attributes for the header
+elements (`h1`-`h6`) in the resulting HTML document.
 
 This extension is included in the standard Markdown library.
 
 Syntax
 ------
 
-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":
+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
     #Header
@@ -32,10 +32,16 @@ Results in:
     <h1 id="header_1">Header</h1>
     <h1 id="header_2">Header</h1>
 
-Configuring the Output
-----------------------
+Usage
+-----
 
-The HeaderId extension has four configuration settings:
+See [Extensions](index.html) for general extension usage, specify `headerid`
+as the name of the extension.
+
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
+
+The following options are provided to configure the output:
 
 * **level**: Base level for headers.
 
@@ -59,8 +65,8 @@ The HeaderId extension has four configuration settings:
     Default: `True`
 
     The `forceid` setting turns on or off the automatically generated ids for 
-    headers that do not have one explicitly defined (using the attr_list 
-    extension).
+    headers that do not have one explicitly defined (using the
+    [Attribute List](attr_list.html) extension).
 
         >>> text = '''
         ... # Some Header
@@ -88,7 +94,7 @@ The HeaderId extension has four configuration settings:
 Using with Meta-Data
 --------------------
 
-The HeaderId Extension also supports the [Meta-Data](meta_data.html) Extension.
+The HeaderId extension also supports the [Meta-Data](meta_data.html) extension.
 Please see the documentation for that extension for specifics. The supported 
 meta-data keywords are:
 
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index b71c2ec..d6d41df 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -79,8 +79,9 @@ Third Party Extensions
 ----------------------
 
 Various individuals and/or organizations have developed extensions which they
-have made available to the public.  A [list of third party
-extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions)
+have made available to the public. A [list of third party extensions][list]
 is maintained on the wiki for your convenience. The Python-Markdown team
 offers no official support for these extensions. Please see the developer of
 each extension for support.
+
+[list]: https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions
diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.txt
index 1695d8b..7ac24e2 100644
--- a/docs/extensions/meta_data.txt
+++ b/docs/extensions/meta_data.txt
@@ -10,15 +10,15 @@ 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.
+The Meta-Data extension adds a syntax for defining meta-data about a document.
+It 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 is included in the standard Markdown library.
 
-This extension has been a part of the Markdown library since 2.0.
+[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
 
 Syntax
 ------
@@ -38,12 +38,23 @@ of a markdown document like this:
 
 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. 
+anything following the colon on the line and may even be blank.
+
+If a line is indented by 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.
+document prior to any further processing by Markdown.
+
+Usage
+-----
+
+See [Extensions](index.html) for general extension usage, specify `meta`
+as the name of the extension.
+
+This extension does not accept any special configuration options.
 
 Accessing the Meta-Data
 -----------------------
@@ -75,14 +86,14 @@ 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 
+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:
+The following extensions are currently known to work with the Meta-Data 
+extension. The keywords they are known to support are also listed.
 
 * [HeaderId](header_id.html)
     * `header_level`
diff --git a/docs/extensions/nl2br.txt b/docs/extensions/nl2br.txt
index ef479fd..0fe20c3 100644
--- a/docs/extensions/nl2br.txt
+++ b/docs/extensions/nl2br.txt
@@ -4,13 +4,19 @@ prev_url:   meta_data.html
 next_title: Sane Lists Extension
 next_url:   sane_lists.html
 
-NL2BR Extension
-===============
+NL2BR
+=====
 
-A Python-Markdown extension to treat newlines as hard breaks; like
+Summary
+-------
+
+The NL2BR extension will cause newlines to be treated as hard breaks; like
 StackOverflow and [GitHub][] flavored Markdown do.
 
-Usage:
+[Github]: http://github.github.com/github-flavored-markdown/
+
+Example
+-------
 
     >>> import markdown
     >>> text = """
@@ -22,4 +28,10 @@ Usage:
     <p>Line 1<br />
     Line 2</p>
 
-[Github]: http://github.github.com/github-flavored-markdown/
+Usage
+-----
+
+See [Extensions](index.html) for general extension usage, specify `nl2br`
+as the name of the extension.
+
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/sane_lists.txt b/docs/extensions/sane_lists.txt
index 7e67e1f..13fa9fe 100644
--- a/docs/extensions/sane_lists.txt
+++ b/docs/extensions/sane_lists.txt
@@ -10,7 +10,7 @@ Sane Lists
 Summary
 -------
 
-The Sane Lists Extension alters the behavior of the Markdown List syntax
+The Sane Lists extension alters the behavior of the Markdown List syntax
 to be less surprising.
 
 This extension is included in the standard Markdown library.
@@ -67,15 +67,7 @@ In all other ways, Sane Lists should behave as normal Markdown lists.
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](index.html) for general extension usage, specify `sane_lists`
+as the name of the extension.
 
-    >>> html = markdown.markdown(text, ['sane_lists'])
-
-To use with other extensions, just add them to the list, like this:
-
-    >>> html = markdown.markdown(text, ['def_list', 'sane_lists'])
-
-The extension can also be called from the command line using Markdown's `-x` 
-parameter:
-
-    python -m markdown -x sane_lists source.txt > output.html
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.txt
index fd3bae6..06b9c9a 100644
--- a/docs/extensions/smart_strong.txt
+++ b/docs/extensions/smart_strong.txt
@@ -10,14 +10,16 @@ Smart_Strong
 Summary
 -------
 
-The Markdown Smart_Strong Extension adds smarter handling of double underscores
-within words. This does for double underscores what
-[smart_emphasis](../reference.html#smart_emphasis) does for single underscores.
+The Smart_Strong extension adds smarter handling of double underscores within
+words. This does for double underscores what [smart_emphasis][] does for single
+underscores.
 
-The Smart_Strong Extension is included in the standard Markdown library.
+The Smart_Strong extension is included in the standard Markdown library.
 
-Usage
------
+[smart_emphasis]: ../reference.html#smart_emphasis
+
+Example
+-------
 
     >>> import markdown
     >>> markdown.markdown('Text with double__underscore__words.', \
@@ -30,8 +32,10 @@ Usage
                           extensions=['smart_strong'])
     u'<p><strong>this__works__too</strong>.</p>'
 
-This extension is also included with the [Extra](extra.html) Extension. You may
-call that extension to get this behavior with all the other features of 'Extra'.
+Usage
+-----
 
-    >>> markdown.markdown(text, extensions=['extra'])
+See [Extensions](index.html) for general extension usage, specify `smart_strong`
+as the name of the extension.
 
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/smarty.txt b/docs/extensions/smarty.txt
index 84c6494..3cef11a 100644
--- a/docs/extensions/smarty.txt
+++ b/docs/extensions/smarty.txt
@@ -21,31 +21,22 @@ ASCII symbol | Unicode replacements
 \--          | &ndash;
 -\--         | &mdash;
 
-Arguments
----------
-
-All three arguments are set to `True` by default.
-
-Argument         | Description
---------         | -----------
-`smart_dashes`   | whether to convert dashes
-`smart_quotes`   | whether to convert quotes
-`smart_ellipses` | whether to convert ellipses
-
 Usage
 -----
 
-Default configuration:
+See [Extensions](index.html) for general extension usage, specify `smarty`
+as the name of the extension.
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['smarty']
-    ... )
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
 
-Disable quotes convertation:
+The following options are provided to configure the output (all three are set to `True` by default):
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['smarty(smart_quotes=False)']
-    ... )
+Option           | Description
+------           | -----------
+`smart_dashes`   | whether to convert dashes
+`smart_quotes`   | whether to convert quotes
+`smart_ellipses` | whether to convert ellipses
 
 Further reading
 ---------------
diff --git a/docs/extensions/tables.txt b/docs/extensions/tables.txt
index bb0872a..46e8437 100644
--- a/docs/extensions/tables.txt
+++ b/docs/extensions/tables.txt
@@ -1,4 +1,4 @@
-title:      Table Extension
+title:      Tables Extension
 prev_title: Footnotes Extension
 prev_url:   footnotes.html
 next_title: Smart Strong Extension
@@ -10,7 +10,7 @@ Tables
 Summary
 -------
 
-The Table Extension adds the ability to create tables in Markdown documents.
+The Tables extension adds the ability to create tables in Markdown documents.
 
 This extension is included in the standard Markdown library.
 
@@ -52,7 +52,7 @@ will be rendered as:
 Usage
 -----
 
-From the Python interpreter:
-
-    >>> html = markdown.markdown(text, ['tables'])
+See [Extensions](index.html) for general extension usage, specify `tables`
+as the name of the extension.
 
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt
index 260129c..d13aadb 100644
--- a/docs/extensions/toc.txt
+++ b/docs/extensions/toc.txt
@@ -1,7 +1,7 @@
 title:      Table of Contents Extension
 prev_title: SmartyPants Extension
 prev_url:   smarty.html
-next_title: Wikilinks Extension
+next_title: WikiLinks Extension
 next_url:   wikilinks.html
 
 Table of Contents
@@ -10,16 +10,17 @@ Table of Contents
 Summary
 -------
 
-Adds a Table of Contents to a Markdown document.
+The Table of Contents extension generates a Table of Contents from a Markdown
+document and adds it into the resulting HTML document.
 
-This extension is included with the Markdown library since version 2.0.
+This extension is included in the standard Markdown library.
 
 Syntax
 ------
 
-Place a marker in the document where you would like the table of contents to
+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:
+marker. The marker defaults to `[TOC]` so the following document:
 
     [TOC]
 
@@ -43,33 +44,45 @@ would generate the following output:
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](index.html) for general extension usage, specify `toc`
+as the name of the extension.
 
-    >>> html = markdown.markdown(some_text, extensions=['toc'])
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
 
 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``.
-* **permalink**: Set to ``True`` to have this extension generate Sphinx-style
-  permanent links near the headers (for use with Sphinx stylesheets).
-
-If a 'marker' is not found in the document, then the toc is available as an
-attribute of the Markdown class. This allows one to insert the toc elsewhere 
-in their page template. For example:
-
-    >>> text = '''
-    # Header 1
-    
-    ## Header 2
-    '''
-    >>> md = markdown.Markdown(extensions=['toc'])
-    >>> html = md.convert(text)
-    >>> render_some_template(context={'body': html, 'toc': md.toc})
+* **marker**:
+    Text to find and replace with the Table of Contents. Defaults
+    to `[TOC]`.
+
+    If a `marker` is not found in the document, then the Table of Contents is
+    available as an attribute of the Markdown class. This allows one to insert
+    the Table of Contents elsewhere in their page template. For example:
+
+        >>> text = '''
+        # Header 1
+        
+        ## Header 2
+        '''
+        >>> md = markdown.Markdown(extensions=['toc'])
+        >>> html = md.convert(text)
+        >>> render_some_template(context={'body': html, 'toc': md.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 the Table of Contents' `<div>`. Defaults to `None`.
+
+* **anchorlink**:
+    Setting to `True` will cause the headers link to themselves. Default is
+    `False`.
+
+* **permalink**:
+    Set to `True` to have this extension generate a Sphinx-style permanent links
+    near the headers (for use with Sphinx stylesheets).
+
diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt
index ca36d17..ea694a8 100644
--- a/docs/extensions/wikilinks.txt
+++ b/docs/extensions/wikilinks.txt
@@ -1,4 +1,4 @@
-title:      Wikilinks Extension
+title:      WikiLinks Extension
 prev_title: Table of Contents Extension
 prev_url:   toc.html
 next_title: Extension API
@@ -10,12 +10,12 @@ WikiLinks
 Summary
 -------
 
-An extension to Python-Markdown that adds [WikiLinks][]. Specifically, any
+The WikiLinks extension adds support for [WikiLinks][]. Specifically, any
 ``[[bracketed]]`` word is converted to a link.
 
-[WikiLinks]: http://en.wikipedia.org/wiki/Wikilink
+This extension is included in the standard Markdown library.
 
-This extension has been included in the Markdown library since 2.0.
+[WikiLinks]: http://en.wikipedia.org/wiki/Wikilink
 
 Syntax
 ------
@@ -25,7 +25,7 @@ number, dashes, underscores and spaces surrounded by double brackets. Therefore
 
     [[Bracketed]]
 
-Would produce the following html:
+would produce the following html:
 
     <a href="/Bracketed/" class="wikilink">Bracketed</a>
 
@@ -33,43 +33,46 @@ 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:
+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
+becomes
 
     <a href="/Wiki_Link/" class="wikilink">Wiki Link</a>
 
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](index.html) for general extension usage, specify `wikilinks`
+as the name of the extension.
 
-    >>> text = "Some text with a [[WikiLink]]."
-    >>> html = markdown.markdown(text, ['wikilinks'])
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
 
 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. Four settings are provided to
-change the default behavior:
+the html class `wikilink`.
+
+The following options are provided to change the default behavior:
 
-1. **base_url**: String to append to beginning of URL.
+* **base_url**: String to append to beginning of URL.
 
     Default: `'/'`
 
-2. **end_url**: String to append to end of URL.
+* **end_url**: String to append to end of URL.
 
     Default: `'/'`
 
-3. **html_class**: CSS hook. Leave blank for none.
+* **html_class**: CSS class. Leave blank for none.
 
     Default: `'wikilink'`
 
-4. **build_url**: Callable which formats the URL from it's parts.
+* **build_url**: Callable which formats the URL from its parts.
+
+### Examples ###
 
 For an example, let us suppose links should always point to the subdirectory
 `/wiki/` and end with `.html`
@@ -95,7 +98,6 @@ could also pass in a callable which must accept three arguments (``label``,
             extension_configs={'wikilinks' : [('build_url', my_url_builder)]}
     )
 
-
 The option is also provided to change or remove the class attribute.
 
     >>> html = markdown.markdown(text,
@@ -106,26 +108,10 @@ 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 -m markdown -x wikilinks(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 = ['wikilinks'],
-    ...     extension_configs = {'wikilinks': [
-    ...                                 ('base_url', 'http://example.com/'),
-    ...                                 ('end_url', '.html'),
-    ...                                 ('html_class', '') ]},
-    ...     safe_mode = True
-    ... )
-    >>> html = md.convert(text)
-
-Using with Meta-Data
---------------------
+Using with Meta-Data extension
+------------------------------
 
-The WikiLink Extension also supports the [Meta-Data](meta_data.html) Extension.
+The WikiLink extension also supports the [Meta-Data](meta_data.html) extension.
 Please see the documentation for that extension for specifics. The supported
 meta-data keywords are: