Various changes to docs for updated changes, clarity, and to fix typos.

1 files changed, 50 insertions, 31 deletions

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 }