Documentation cleanup.

.spell-dict

@@ -113,6 +113,7 @@ stdout
 Stelios
 Stienstra
 subclasses
+SuperFences
 svn
 Swartz
 Szakmeister

docs/authors.md

@@ -6,7 +6,7 @@ Primary Authors
 * __[Waylan Limberg](https://github.com/waylan)__
 
     @waylan is the current maintainer of the code and has written much of the
-    current code base, included a complete refactor of the core for version 2.0.
+    current code base, including a complete refactor of the core for version 2.0.
     He started out by authoring many of the available extensions and later was
     asked to join Yuri, where he began fixing numerous bugs, adding
     documentation and making general improvements to the existing code base.

docs/cli.md

@@ -55,7 +55,7 @@ path.
 * **Windows**:
 
     Assuming a default install of Python on Windows, your "Scripts" directory
-    is most likely something like `C:\\Python26\Scripts`. Verify the location
+    is most likely something like `C:\\Python37\Scripts`. Verify the location
     of your "Scripts" directory and add it to you system path.
 
     Calling `markdown_py` from the command line will call the wrapper batch

docs/extensions/fenced_code_blocks.md

@@ -34,6 +34,10 @@ part of the list.
 
     Fenced Code Blocks are only supported at the document root level.
     Therefore, they cannot be nested inside lists or blockquotes.
+    If you need to nest fenced code blocks, you may want to try the
+    the third party extension [SuperFences] instead.
+
+[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 
 ### Language
 

docs/reference.md

@@ -25,7 +25,7 @@ instance of the `markdown.Markdown` class and pass multiple documents through
 it. If you do use a single instance though, make sure to call the `reset`
 method appropriately ([see below](#convert)).
 
-### markdown.markdown(text [, **kwargs]) {: #markdown }
+### markdown.markdown(text [, **kwargs]) {: #markdown data-toc-label='markdown.markdown' }
 
 The following options are available on the `markdown.markdown` function:
 
@@ -34,24 +34,20 @@ __text__{: #text }
 :   The source Unicode string. (required)
 
     !!! 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:
+        Python-Markdown expects a **Unicode** string as input (some simple ASCII binary strings *may* work only by
+        coincidence) and returns output as a Unicode string. Do not pass binary strings to it! If your input is
+        encoded, (e.g. as UTF-8), it is your responsibility to decode it.  For example:
 
             :::python
-            input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
-            text = input_file.read()
+            with open("some_file.txt", "r", encoding="utf-8") as input_file:
+                text = input_file.read()
             html = markdown.markdown(text)
 
         If you want to write the output to disk, you *must* encode it yourself:
 
             :::python
-            output_file = codecs.open("some_file.html", "w",
-                                      encoding="utf-8",
-                                      errors="xmlcharrefreplace"
-            )
-            output_file.write(html)
+            with open("some_file.html", "w", encoding="utf-8", errors="xmlcharrefreplace") as output_file:
+                output_file.write(html)
 
 __extensions__{: #extensions }
 
@@ -181,7 +177,7 @@ __tab_length__{: #tab_length }:
 
 : Length of tabs in the source. Default: 4
 
-### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile }
+### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile data-toc-label='markdown.markdownFromFile' }
 
 With a few exceptions, `markdown.markdownFromFile` accepts the same options as
 `markdown.markdown`. It does **not** accept a `text` (or Unicode) string.
@@ -220,7 +216,7 @@ __encoding__{: #encoding }
         meet your specific needs, it is suggested that you write your own code
         to handle your encoding/decoding needs.
 
-### markdown.Markdown([**kwargs]) {: #Markdown }
+### markdown.Markdown([**kwargs]) {: #Markdown data-toc-label='markdown.Markdown' }
 
 The same options are available when initializing the `markdown.Markdown` class
 as on the [`markdown.markdown`](#markdown) function, except that the class does
@@ -233,7 +229,7 @@ string must be passed to one of two instance methods.
     the thread they were created in. A single instance should not be accessed
     from multiple threads.
 
-#### Markdown.convert(source) {: #convert }
+#### Markdown.convert(source) {: #convert data-toc-label='Markdown.convert' }
 
 The `source` text must meet the same requirements as the [`text`](#text)
 argument of the [`markdown.markdown`](#markdown) function.
@@ -248,8 +244,7 @@ html2 = md.convert(text2)
 ```
 
 Depending on which options and/or extensions are being used, the parser may
-need its state reset between each call to `convert`, otherwise performance
-can degrade drastically:
+need its state reset between each call to `convert`.
 
 ```python
 html1 = md.convert(text1)
@@ -263,7 +258,7 @@ To make this easier, you can also chain calls to `reset` together:
 html3 = md.reset().convert(text3)
 ```
 
-#### Markdown.convertFile(**kwargs) {: #convertFile }
+#### Markdown.convertFile(**kwargs) {: #convertFile data-toc-label='Markdown.convertFile' }
 
 The arguments of this method are identical to the arguments of the same
 name on the `markdown.markdownFromFile` function ([`input`](#input),