From 8aa2fc7b5138fd97ded7dd1e70103532a9fd6583 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan@gmail.com>
Date: Tue, 19 Feb 2013 16:33:36 -0500
Subject: Various changes to docs for updated changes, clarity, and to fix
 typos.

---
 docs/cli.txt                         | 23 +++++-----
 docs/extensions/abbreviations.txt    |  2 +-
 docs/extensions/api.txt              | 62 +++++++++++++++++----------
 docs/extensions/attr_list.txt        | 12 +++---
 docs/extensions/code_hilite.txt      | 30 +++++++------
 docs/extensions/definition_lists.txt |  4 +-
 docs/extensions/extra.txt            |  5 ---
 docs/extensions/index.txt            | 79 +++++++++++++++--------------------
 docs/extensions/wikilinks.txt        |  6 +--
 docs/index.txt                       | 10 ++---
 docs/install.txt                     | 16 -------
 docs/reference.txt                   | 81 ++++++++++++++++++++++--------------
 docs/siteindex.txt                   |  1 +
 13 files changed, 171 insertions(+), 160 deletions(-)

diff --git a/docs/cli.txt b/docs/cli.txt
index 9babc50..719bc0c 100644
--- a/docs/cli.txt
+++ b/docs/cli.txt
@@ -21,8 +21,8 @@ Assuming the `python` executable is on your system path, just run the following:
 
     python -m markdown [options] [args]
 
-That will run the module as a script. Note that on older Python versions (2.5 
-and 2.6), you may need to specify the appropriate module:
+That will run the module as a script. Note that on older Python versions (2.6), 
+you may need to specify the appropriate module:
 
     python -m markdown.__main__ [options] [args]
 
@@ -30,8 +30,8 @@ Use the `--help` option for available options:
 
     python -m markdown --help
 
-If you are using Python 2.4 or you don't want to have to call the python
-executable directly, follow the instructions below:
+If you don't want to call the python executable directly, follow the 
+instructions below:
 
 Setup
 -----
@@ -70,13 +70,14 @@ path.
     markdown text files will not likely be in that directory, so it is much 
     more convenient to have ``markdown_py`` on your path.
 
-__Note:__ Python-Markdown uses "markdown_py" as a script name because
-the Perl implementation has already taken the more obvious name "markdown".
-Additionally, the default Python configuration on some systems would cause a 
-script named "markdown.py" to fail by importing itself rather than the markdown
-library. Therefore, the script has been named "markdown_py" as a compromise. If
-you prefer a different name for the script on your system, it is suggested that
-you create a symbolic link to `markdown_py` with your preferred name.
+!!!Note 
+    Python-Markdown uses "markdown_py" as a script name because
+    the Perl implementation has already taken the more obvious name "markdown".
+    Additionally, the default Python configuration on some systems would cause a 
+    script named "markdown.py" to fail by importing itself rather than the markdown
+    library. Therefore, the script has been named "markdown_py" as a compromise. If
+    you prefer a different name for the script on your system, it is suggested that
+    you create a symbolic link to `markdown_py` with your preferred name.
 
 Usage
 -----
diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.txt
index fa38f50..21d90bf 100644
--- a/docs/extensions/abbreviations.txt
+++ b/docs/extensions/abbreviations.txt
@@ -56,4 +56,4 @@ To use with other extensions, just add them to the list, like this:
 Abbreviations can also be called from the command line using Markdown's `-x` 
 parameter, like so:
 
-    markdown.py -x abbr source.txt > output.html
+    python -m markdown -x abbr source.txt > output.html
diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index 69fb68e..ac840f9 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -562,27 +562,10 @@ values, and should be converted at run time. For example:
 
 ### makeExtension {: #makeextension }
 
-Each extension should ideally be placed in its own module starting
-with the  ``mdx_`` prefix (e.g. ``mdx_footnotes.py``).  The module must
-provide a module-level function called ``makeExtension`` that takes
-an optional parameter consisting of a dictionary of configuration over-rides 
-and returns an instance of the extension.  An example from the footnote 
-extension:
-
-    def makeExtension(configs=None) :
-        return FootnoteExtension(configs=configs)
-
-By following the above example, when Markdown is passed the name of your 
-extension as a string (i.e.: ``'footnotes'``), it will automatically import
-the module and call the ``makeExtension`` function initiating your extension.
+As noted in the [library reference] an instance of an extension can be passed
+directly to Markdown. In fact, this is the prefered way to use third-party 
+extensions.
 
-You may have noted that the extensions packaged with Python-Markdown do not
-use the ``mdx_`` prefix in their module names. This is because they are all
-part of the ``markdown.extensions`` package. Markdown will first try to import
-from ``markdown.extensions.extname`` and upon failure, ``mdx_extname``. If both
-fail, Markdown will continue without the extension.
-
-However, Markdown will also accept an already existing instance of an extension.
 For example:
 
     import markdown
@@ -591,8 +574,42 @@ For example:
     myext = myextension.MyExtension(configs=configs)
     md = markdown.Markdown(extensions=[myext])
 
-This is useful if you need to implement a large number of extensions with more
-than one residing in a module.
+This is especially useful if you need to implement a large number of extensions 
+with more than one residing in a module.
+
+However, for historical reasons, Markdown also accepts "named" third party 
+extensions. In that case, only one extension can be defined per module
+and that extension must define a module-level function called 
+`makeExtension` that takes an optional parameter consisting of a dictionary 
+of configuration over-rides and returns an instance of the extension.  For example:
+
+    class MyExtension(markdown.extensions.Extension)
+        # Define extension here...
+
+    def makeExtension(configs=None):
+        return MyExtension(configs=configs)
+
+When Markdown is passed the "name" of your extension as a string, it will import 
+the module and call the `makeExtension` function to initiate your extension.
+
+The "name" of your extension must be a string consisting of the importable path to
+your module using Python's dot notation. Therefore, if you are providing a library
+to your users and would like to include a custom markdown extensions with your 
+library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py`
+contains the `makeExtension` function and the `mylib` directory is on the PYTHONPATH.
+
+You may have noted that the extensions packaged with Python-Markdown do not
+use  Python's dot notation in their names. This is because they are 
+all part of the `markdown.extensions` package. If a "name" contains any dots 
+(`.`), then it will be imported as-is. Otherwise, Markdown will first try to 
+import from `markdown.extensions.extname` and upon failure, `mdx_extname` where
+`"extname"` is the "name" passed to Markdown.
+
+!!! Note
+    While the `mdx_extname` method of naming extensions is still supported, it 
+    remains solely for historical reasons to support the various existing 
+    third-party extensions. This method is discouraged going forward and support
+    may be removed in a future release.
 
 [Preprocessors]: #preprocessors
 [InlinePatterns]: #inlinepatterns
@@ -610,3 +627,4 @@ than one residing in a module.
 [Available Extensions]: index.html 
 [Footnotes]: footnotes.html
 [Definition Lists]: definition_lists.html
+[library reference]: ../reference.html
diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt
index 4134a82..54a61d0 100644
--- a/docs/extensions/attr_list.txt
+++ b/docs/extensions/attr_list.txt
@@ -26,14 +26,14 @@ The basic syntax was inspired by [Maruku][]'s Attribute List feature.
 
 An example attribute list might look like this:
 
-    {: #someid .someclass somekey='some values' }
+    {: #someid .someclass somekey='some value' }
 
-A word which starts with a hash `#` will set the id of an element.
+A word which starts with a hash (`#`) will set the id of an element.
 
-A word which starts with a dot `.` will add to the list of classes assigned to
-an element.
+A word which starts with a dot (`.`) will be added to the list of classes 
+assigned to an element.
 
-A key/value pair will assign that pair to the element.
+A key/value pair (`somekey='some value'`) will assign that pair to the element.
 
 Be aware that while the dot syntax will add to a class, using key/value pairs
 will always override the previously defined attribute. Consider the following:
@@ -42,7 +42,7 @@ will always override the previously defined attribute. Consider the following:
 
 The above example would result in the following attributes being defined:
 
-    id="id2 class="class2 class3 class4"
+    id="id2" class="class2 class3 class4"
 
 ### Block Level ###
 
diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
index 31ecfbb..57f81ca 100644
--- a/docs/extensions/code_hilite.txt
+++ b/docs/extensions/code_hilite.txt
@@ -30,8 +30,9 @@ 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.
+!!! Note
+    The css and/or javascript is not included as part of this extension
+    but shall always be provided by the end user.
 
 Syntax
 ------
@@ -42,11 +43,11 @@ the code block. There are three ways to tell the hiliter what language the code
 block contains and each one has a different result.
 
 !!! Note
-The format of the language identifier only effects the display of line numbers
-if `linenums` is set to `None` (the default). If set to `True` or `False`
-(see [Usage](#usage) below) the format of the identifier has no effect on the
-display of line numbers -- it only serves as a means to define the language
-of the code block.
+    The format of the language identifier only effects the display of line numbers
+    if `linenums` is set to `None` (the default). If set to `True` or `False`
+    (see [Usage](#usage) below) the format of the identifier has no effect on the
+    display of line numbers -- it only serves as a means to define the language
+    of the code block.
 
 [syntax]: http://daringfireball.net/projects/markdown/syntax#precode
 
@@ -93,10 +94,8 @@ Will result in:
 ###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.
+encountered that does not define a language, the block is simply wrapped in
+`<pre>` tags and output. 
 
         # Code goes here ...
 
@@ -106,9 +105,14 @@ Will result in:
 
 Lets see the source for that:
 
-    <div class="codehilite" ><pre><code># Code goes here ...
+    <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
 -----
 
@@ -131,7 +135,7 @@ SheBangs (`#!`) for language identification, set `linenums` to `False`.
     ... )
 
 If you want to prevent Pygments from guessing the language, only highlighting
-blocks when you explicitly request it, set the `guess_lang` setting to 'False'.
+blocks when you explicitly request it, set the `guess_lang` setting to `False`.
 
     >>> html = markdown.markdown(text,
     ...     extensions=['codehilite(guess_lang=False)']
diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.txt
index 53f14a0..a5ba393 100644
--- a/docs/extensions/definition_lists.txt
+++ b/docs/extensions/definition_lists.txt
@@ -10,7 +10,7 @@ Definition Lists
 Summary
 -------
 
-The Definition List Extension adds the ability to create definition list in
+The Definition List Extension adds the ability to create definition lists in
 Markdown documents.
 
 This extension is included in the standard Markdown library.
@@ -58,4 +58,4 @@ To use with other extensions, just add them to the list, like this:
 The extension can also be called from the command line using Markdown's `-x` 
 parameter:
 
-    markdown.py -x def_list source.txt > output.html
+    python -m markdown -x def_list source.txt > output.html
diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt
index adafe07..d747496 100644
--- a/docs/extensions/extra.txt
+++ b/docs/extensions/extra.txt
@@ -34,11 +34,6 @@ From the Python interpreter:
     >>> import markdown
     >>> html = markdown.markdown(text, ['extra'])
 
-In the unlikely event that one or more of the supported extensions are not
-available for import, Markdown will simply continue without that
-extension. If you would like to be notified of such failures,
-you may set Python-Markdown's logger level to "WARN".
-
 There may be [additional extensions](index.html) that are distributed with
 Python-Markdown that are not included here in Extra. The features 
 of those extensions are not part of PHP Markdown Extra, and 
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 5cbdd7d..99ca8c7 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -12,16 +12,22 @@ Python Markdown offers a flexible extension mechanism, which makes it possible
 to change and/or extend the behavior of the parser without having to edit the
 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.
+To use an extension, pass it to markdown with the `extensions` keyword.
+
+    markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'footnotes'])
 
-    markdown.markdown(some_text, extensions=['footnotes', 'nl2br'])
+See the [Library Reference](../reference.html#extensions) for more details.
 
-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.
+From the command line, specify an extension with the `-x` option. 
 
     python -m markdown -x footnotes -x tables input.txt > output.html
 
+See the [Command Line docs](../cli.html) or use the `--help` option for more details.
+
+!!! seealso "See Also"
+    If you would like to write your own extensions, see the
+    [Extension API](api.html) for details.
+
 Officially Supported Extensions
 -------------------------------
 
@@ -29,25 +35,29 @@ The extensions listed below are included with (at least) the most recent release
 and are officially supported by Python-Markdown. Any documentation is
 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.
-
-### 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`
-
+available to you using the "name" listed in the second column below.
+
+Extension                            | "Name"
+------------------------------------ | ---------------
+[Extra]                              | `extra`
+&nbsp; &nbsp; [Abbreviations][]      | `abbr`
+&nbsp; &nbsp; [Attribute Lists][]    | `attr_list`
+&nbsp; &nbsp; [Definition Lists][]   | `def_list`
+&nbsp; &nbsp; [Fenced Code Blocks][] | `fenced_code`
+&nbsp; &nbsp; [Footnotes][]          | `footnotes`
+&nbsp; &nbsp; [Tables][]             | `tables`
+&nbsp; &nbsp; [Smart Strong][]       | `smart_strong`
+[Admonition][]                       | `admonition`
+[CodeHilite][]                       | `codehilite`
+[HTML Tidy][]                        | `html_tidy`
+[HeaderId]                           | `headerid`
+[Meta-Data]                          | `meta`
+[New Line to Break]                  | `nl2br`
+[Sane Lists]                         | `sane_lists`
+[Table of Contents]                  | `toc`
+[WikiLinks]                          | `wikilinks`
+
+[Extra]: extra.html
 [Abbreviations]: abbreviations.html
 [Attribute Lists]: attr_list.html
 [Definition Lists]: definition_lists.html
@@ -55,24 +65,6 @@ Extension              | Name in Python-Markdown
 [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`
-[Sane Lists]        | `sane_lists`
-[Table of Contents] | `toc`
-[WikiLinks]         | `wikilinks`
-
 [Admonition]: admonition.html
 [CodeHilite]: code_hilite.html
 [HTML Tidy]: html_tidy.html
@@ -92,6 +84,3 @@ extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extension
 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.
-
-If you would like to write your own extensions, see the
-[Extensions API](api.html) for details.
diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt
index 5f6d20e..ed191e3 100644
--- a/docs/extensions/wikilinks.txt
+++ b/docs/extensions/wikilinks.txt
@@ -54,7 +54,7 @@ From the Python interpreter:
 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 
+customize that behavior within Python code. Four settings are provided to 
 change the default behavior:
 
 1. **base_url**: String to append to beginning of URL. 
@@ -108,7 +108,7 @@ Would cause all wikilinks to be assigned to the class `myclass`.
 
 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
+    python -m markdown -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:
 
@@ -133,7 +133,7 @@ meta-data keywords are:
 * `wiki_end_url`
 * `wiki_html_class`
 
-When used, the meta-data will override the settings provided through the  
+When used, the meta-data will override the settings provided through the
 `extension_configs` interface. 
 
 This document:
diff --git a/docs/index.txt b/docs/index.txt
index b44f5ae..90accf2 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -26,8 +26,8 @@ The Python-Markdown project is developed with the following goals in mind:
   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.
+* Provide an [Extension API](extensions/api.html) which makes it possible
+  to change and/or extend the behavior of the parser.
 
 Features
 --------
@@ -44,9 +44,9 @@ features:
 * __Extensions__
 
     Various [extensions](extensions/index.html) are provided (including 
-    [extra](extensions/extra.html)) to expand the base syntax. Additionally, 
-    a public [Extension API](extensions/api.html) is available to write 
-    your own extensions.
+    [extra](extensions/extra.html)) to change and/or extend the base syntax. 
+    Additionally, a public [Extension API](extensions/api.html) is available 
+    to write your own extensions.
 
 * __Output Formats__
 
diff --git a/docs/install.txt b/docs/install.txt
index 776bb17..3e55c77 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -65,19 +65,3 @@ command line:
     git clone git://github.com/waylan/Python-Markdown.git python-markdown
     cd python-markdown
     python setup.py install
-
-Dependencies
-------------
-
-Python-Markdown requires the ElementTree module to be installed. In Python 2.5+ 
-ElementTree is included as part of the standard library at 
-`xml.etree.ElementTree` and/or `xml.etree.cElementTree`. For earlier versions 
-of Python, the library needs to be installed.  However, Python-Markdown's 
-install script will automaticaly detect the missing library and download and 
-install the "ElementTree" library for you if your system has internet access. 
-If you would like to use the "cElementTree" library (which is faster), you can 
-install it manually. Markdown will check for the faster "c" library first and 
-fall back to the slower python implementation when it is not available.
-
-See <http://effbot.org/zone/element-index.htm> for more information or to 
-download the latest version of ElementTree.
diff --git a/docs/reference.txt b/docs/reference.txt
index 8117e69..fa32972 100644
--- a/docs/reference.txt
+++ b/docs/reference.txt
@@ -34,24 +34,25 @@ it.
 
 The following options are available on the `markdown.markdown` function:
 
-* __`text`__{: #text } (required): The source text string.
+* __`text`__{: #text } (required): The source unicode string.
 
-    Note that Python-Markdown expects **Unicode** as input (although
-    a simple ASCII string may work) and returns output as Unicode.
-    Do not pass encoded strings to it! If your input is encoded, (e.g. as 
-    UTF-8), it is your responsibility to decode it.  For example:
+    !!! note "Important"
+        Python-Markdown expects **Unicode** as input (although
+        some simple ASCII strings *may* work) and returns output as Unicode.
+        Do not pass encoded strings to it! If your input is encoded, (e.g. as 
+        UTF-8), it is your responsibility to decode it.  For example:
 
-        input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
-        text = input_file.read()
-        html = markdown.markdown(text)
+            input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
+            text = input_file.read()
+            html = markdown.markdown(text)
 
-    If you want to write the output to disk, you must encode it yourself:
+        If you want to write the output to disk, you *must* encode it yourself:
 
-        output_file = codecs.open("some_file.html", "w", 
-                                  encoding="utf-8", 
-                                  errors="xmlcharrefreplace"
-        )
-        output_file.write(html)
+            output_file = codecs.open("some_file.html", "w", 
+                                      encoding="utf-8", 
+                                      errors="xmlcharrefreplace"
+            )
+            output_file.write(html)
 
 * __`extensions`__{: #extensions }: A list of extensions.
 
@@ -98,8 +99,9 @@ The following options are available on the `markdown.markdown` function:
     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.
+    !!! seealso "See Also"
+        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.
@@ -134,10 +136,12 @@ The following options are available on the `markdown.markdown` function:
     * `"html5"`: Outputs HTML style tags of HTML 5
     * `"html"`: Outputs latest supported version of HTML (currently HTML 4).
 
-    Note that it is suggested that the more specific formats ("xhtml1",
-    "html5", & "html4") be used as "xhtml" or "html" may change in the future
-    if it makes sense at that time. The values can either be lowercase or 
-    uppercase.
+    The values can be in either lowercase or uppercase.
+
+    !!! warning
+        It is suggested that the more specific formats ("xhtml1", "html5", & 
+        "html4") be used as the more general formats ("xhtml" or "html") may 
+        change in the future if it makes sense at that time. 
 
 * __`safe_mode`__{: #safe_mode }: Disallow raw html.
 
@@ -145,7 +149,7 @@ The following options are available on the `markdown.markdown` function:
     provided by untrusted users, you may want to use the "safe_mode" 
     option which ensures that the user's HTML tags are either replaced, 
     removed or escaped. (They can still create links using Markdown syntax.)
-
+    
     The following values are accepted:
 
     * `False` (Default): Raw HTML is passed through unaltered.
@@ -172,8 +176,21 @@ The following options are available on the `markdown.markdown` function:
 
             <p>Foo &lt;b&gt;bar&lt;/b&gt;.</p>
 
-    Note that "safe_mode" also alters the default value for the 
-    [`enable_attributes`](#enable_attributes) option.
+    !!! Note 
+        "safe_mode" also alters the default value for the 
+        [`enable_attributes`](#enable_attributes) option.
+    
+    !!! seealso "See Also"
+        HTML sanitizers (like [Bleach]) may provide a better solution for 
+        dealing with markdown text submitted by untrusted users. That way, 
+        both the HTML generated by Markdown and user submited raw HTML are 
+        fully sanitized.
+    
+            import markdown
+            import bleach
+            html = bleach.clean(markdown.markdown(evil_text))
+    
+[Bleach]: https://github.com/jsocol/bleach
 
 * __`html_replacement_text`__{: #html_replacement_text }: Text used when 
   safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`.
@@ -184,10 +201,11 @@ The following options are available on the `markdown.markdown` function:
   attributes. Defaults to `True`, unless [`safe_mode`](#safe_mode) is enabled, 
   in which case the default is `False`.
 
-    Note that `safe_mode` only overrides the default. If `enable_attributes` 
-    is explicitly set, the explicit value is used regardless of `safe_mode`.
-    However, this could potentially allow an untrusted user to inject
-    JavaScript into your documents.
+    !!! Note 
+        `safe_mode` only overrides the default. If `enable_attributes` 
+        is explicitly set, the explicit value is used regardless of `safe_mode`.
+        However, this could potentially allow an untrusted user to inject
+        JavaScript into your documents.
 
 * __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_` 
   intelligently Default: True
@@ -239,10 +257,11 @@ Instead, it accepts the following required options:
   to "utf-8". The same encoding will always be used for input and output. 
   The 'xmlcharrefreplace' error handler is used when encoding the output.
 
-    **Note:** This is the only place that decoding and encoding of unicode
-    takes place in Python-Markdown. If this rather naive solution does not
-    meet your specific needs, it is suggested that you write your own code
-    to handle your encoding/decoding needs.
+    !!! Note 
+        This is the only place that decoding and encoding of unicode
+        takes place in Python-Markdown. If this rather naive solution does not
+        meet your specific needs, it is suggested that you write your own code
+        to handle your encoding/decoding needs.
 
 ### `markdown.Markdown ([**kwargs])` {: #Markdown }
 
diff --git a/docs/siteindex.txt b/docs/siteindex.txt
index 9c726bd..3844079 100644
--- a/docs/siteindex.txt
+++ b/docs/siteindex.txt
@@ -65,6 +65,7 @@ Table of Contents
     * [Unit Tests](test_suite.html#unit-tests)
     * [Doc Tests](test_suite.html#doc-tests)
 * [Change Log](change_log.html)
+    * [Release Notes for v.2.3](release-2.3.html)
     * [Release Notes for v.2.2.1](release-2.1.1.html)
     * [Release Notes for v.2.2.0](release-2.1.0.html)
     * [Release Notes for v.2.0.2](release-2.0.2.html)
-- 
cgit v1.2.3