Update 3.0 release notes

And other docs cleanup.

10 files changed, 183 insertions, 144 deletions

diff --git a/docs/extensions/api.md b/docs/extensions/api.md
index a110cef..c236a93 100644
--- a/docs/extensions/api.md
+++ b/docs/extensions/api.md
@@ -495,25 +495,24 @@ configuration options for your extension and attach the various processors and
 patterns to the Markdown instance.
 
 It is important to note that the order of the various processors and patterns
-matters. For example, if we replace `http://...` links with `<a>` elements,
-and *then* try to deal with  inline HTML, we will end up with a mess.
-Therefore, the various types of processors and patterns are stored within an
-instance of the Markdown class in [OrderedDict][]s. Your `Extension` class
-will need to manipulate those OrderedDicts appropriately. You may insert
-instances of your processors and patterns into the appropriate location in an
-OrderedDict, remove a built-in instance, or replace a built-in instance with
-your own.
+matters. For example, if we replace `http://...` links with `<a>` elements, and
+*then* try to deal with  inline HTML, we will end up with a mess. Therefore, the
+various types of processors and patterns are stored within an instance of the
+Markdown class in a [Registry][]. Your `Extension` class will need to manipulate
+those registries appropriately. You may `register` instances of your processors
+and patterns with an appropriate priority, `deregister` built-in instances, or
+replace a built-in instance with your own.
 
 ### `extendMarkdown` {: #extendmarkdown }
 
 The `extendMarkdown` method of a `markdown.extensions.Extension` class
-accepts two arguments:
+accepts one argument:
 
 * **`md`**:
 
     A pointer to the instance of the Markdown class. You should use this to
-    access the [OrderedDict][]s of processors and patterns. They are found
-    under the following attributes:
+    access the [Registries][Registry] of processors and patterns. They are
+    found under the following attributes:
 
     * `md.preprocessors`
     * `md.inlinePatterns`
@@ -529,14 +528,9 @@ accepts two arguments:
     * `md.output_format`
     * `md.serializer`
     * `md.registerExtension()`
-    * `md.html_replacement_text`
     * `md.tab_length`
-    * `md.enable_attributes`
-    * `md.smart_emphasis`
-
-* **`md_globals`**:
-
-    Contains all the various global variables within the markdown module.
+    * `md.block_level_elements`
+    * `md.isBlockLevel()`
 
 !!! Warning
     With access to the above items, theoretically you have the option to
@@ -554,109 +548,75 @@ A simple example:
 from markdown.extensions import Extension
 
 class MyExtension(Extension):
-    def extendMarkdown(self, md, md_globals):
-        # Insert instance of 'mypattern' before 'references' pattern
-        md.inlinePatterns.add('mypattern', MyPattern(md), '<references')
+    def extendMarkdown(self, md):
+        # Register instance of 'mypattern' with a priority of 175
+        md.inlinePatterns.register(MyPattern(md), 'mypattern', 175)
 ```
 
-### OrderedDict {: #ordereddict }
-
-An OrderedDict is a dictionary like object that retains the order of it's
-items. The items are ordered in the order in which they were appended to
-the OrderedDict. However, an item can also be inserted into the OrderedDict
-in a specific location in relation to the existing items.
-
-Think of OrderedDict as a combination of a list and a dictionary as it has
-methods common to both. For example, you can get and set items using the
-`od[key] = value` syntax and the methods `keys()`, `values()`, and
-`items()` work as expected with the keys, values and items returned in the
-proper order. At the same time, you can use `insert()`, `append()`, and
-`index()` as you would with a list.
-
-Generally speaking, within Markdown extensions you will be using the special
-helper method `add()` to add additional items to an existing OrderedDict.
+### Registry
 
-The `add()` method accepts three arguments:
+The `markdown.util.Registry` class is a priority sorted registry which Markdown
+uses internally to determine the processing order of its various processors and
+patterns.
 
-* **`key`**: A string. The key is used for later reference to the item.
+A `Registry` instance provides two public methods to alter the data of the
+registry: `register` and `deregister`. Use `register` to add items and
+`deregister` to remove items. See each method for specifics.
 
-* **`value`**: The object instance stored in this item.
+When registering an item, a "name" and a "priority" must be provided. All
+items are automatically sorted by "priority" from highest to lowest. The
+"name" is used to remove (`deregister`) and get items.
 
-* **`location`**: The items location in relation to other items.
+A `Registry` instance is like a list (which maintains order) when reading
+data. You may iterate over the items, get an item and get a count (length)
+of all items. You may also check that the registry contains an item.
 
-    Note that the location can consist of a few different values:
+When getting an item you may use either the index of the item or the
+string-based "name". For example:
 
-    * The special strings `"_begin"` and `"_end"` insert that item at the
-      beginning or end of the OrderedDict respectively.
-
-    * A less-than sign (`<`) followed by an existing key (i.e.:
-      `"<somekey"`) inserts that item before the existing key.
-
-    * A greater-than sign (`>`) followed by an existing key (i.e.:
-      `">somekey"`) inserts that item after the existing key.
-
-Consider the following example:
-
-```pycon
->>> from markdown.odict import OrderedDict
->>> od = OrderedDict()
->>> od['one'] =  1           # The same as: od.add('one', 1, '_begin')
->>> od['three'] = 3          # The same as: od.add('three', 3, '>one')
->>> od['four'] = 4           # The same as: od.add('four', 4, '_end')
->>> od.items()
-[("one", 1), ("three", 3), ("four", 4)]
-```
+    registry = Registry()
+    registry.register(SomeItem(), 'itemname', 20)
+    # Get the item by index
+    item = registry[0]
+    # Get the item by name
+    item = registry['itemname']
 
-Note that when building an OrderedDict in order, the extra features of the
-`add` method offer no real value and are not necessary. However, when
-manipulating an existing OrderedDict, `add` can be very helpful. So let's
-insert another item into the OrderedDict.
+When checking that the registry contains an item, you may use either the
+string-based "name", or a reference to the actual item. For example:
 
-```pycon
->>> od.add('two', 2, '>one')         # Insert after 'one'
->>> od.values()
-[1, 2, 3, 4]
-```
+    someitem = SomeItem()
+    registry.register(someitem, 'itemname', 20)
+    # Contains the name
+    assert 'itemname' in registry
+    # Contains the item instance
+    assert someitem in registry
 
-Now let's insert another item.
+`markdown.util.Registry` has the following methods:
 
-```pycon
->>> od.add('two-point-five', 2.5, '<three') # Insert before 'three'
->>> od.keys()
-["one", "two", "two-point-five", "three", "four"]
-```
+#### `Registry.register(self, item, name, priority)` {: #registry.register }
 
-Note that we also could have set the location of "two-point-five" to be 'after two'
-(i.e.: `'>two'`). However, it's unlikely that you will have control over the
-order in which extensions will be loaded, and this could affect the final
-sorted order of an OrderedDict. For example, suppose an extension adding
-"two-point-five" in the above examples was loaded before a separate extension
-which adds 'two'. You may need to take this into consideration when adding your
-extension components to the various markdown OrderedDicts.
+:   Add an item to the registry with the given name and priority.
 
-Once an OrderedDict is created, the items are available via key:
+    Parameters:
 
-```python
-MyNode = od['somekey']
-```
+    * `item`: The item being registered.
+    * `name`: A string used to reference the item.
+    * `priority`: An integer or float used to sort against all items.
 
-Therefore, to delete an existing item:
+    If an item is registered with a "name" which already exists, the existing
+    item is replaced with the new item. Tread carefully as the old item is lost
+    with no way to recover it. The new item will be sorted according to its
+    priority and will **not** retain the position of the old item.
 
-```python
-del od['somekey']
-```
+#### `Registry.deregister(self, name, strict=True)`  {: #registry.deregister }
 
-To change the value of an existing item (leaving location unchanged):
+:   Remove an item from the registry.
 
-```python
-od['somekey'] = MyNewObject()
-```
+    Set `strict=False` to fail silently.
 
-To change the location of an existing item:
+#### `Registry.get_index_for_name(self, name)` {: #registry.get_index_for_name }
 
-```python
-t.link('somekey', '<otherkey')
-```
+:   Return the index of the given `name`.
 
 ### registerExtension {: #registerextension }
 
@@ -682,7 +642,7 @@ To register an extension, call `md.registerExtension` from within your
 `extendMarkdown` method:
 
 ```python
-def extendMarkdown(self, md, md_globals):
+def extendMarkdown(self, md):
     md.registerExtension(self)
     # insert processors and patterns here
 ```
@@ -850,7 +810,7 @@ module and call the `makeExtension` function to initiate your extension.
 [workingwithetree]: #working_with_et
 [Integrating your code into Markdown]: #integrating_into_markdown
 [extendMarkdown]: #extendmarkdown
-[OrderedDict]: #ordereddict
+[Registry]: #registry
 [registerExtension]: #registerextension
 [Config Settings]: #configsettings
 [makeExtension]: #makeextension
diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md
index 552a82d..153a57c 100644
--- a/docs/extensions/code_hilite.md
+++ b/docs/extensions/code_hilite.md
@@ -132,6 +132,15 @@ Certain lines can be selected for emphasis with the colon syntax. When
 using Pygments' default CSS styles, emphasized lines have a yellow background.
 This is useful to direct the reader's attention to specific lines.
 
+```md
+    :::python hl_lines="1 3"
+    # This line is emphasized
+    # This line isn't
+    # This line is emphasized
+```
+
+Will result in:
+
     :::python hl_lines="1 3"
     # This line is emphasized
     # This line isn't
diff --git a/docs/extensions/extra.md b/docs/extensions/extra.md
index 3d9f374..a74d175 100644
--- a/docs/extensions/extra.md
+++ b/docs/extensions/extra.md
@@ -15,7 +15,6 @@ The supported extensions include:
 * [Fenced Code Blocks](fenced_code_blocks.md)
 * [Footnotes](footnotes.md)
 * [Tables](tables.md)
-* [Smart Strong](smart_strong.md)
 
 See each individual extension for syntax documentation. Extra and all its
 supported extensions are included in the standard Markdown library.
diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md
index 4c8058d..410d652 100644
--- a/docs/extensions/fenced_code_blocks.md
+++ b/docs/extensions/fenced_code_blocks.md
@@ -104,9 +104,9 @@ The lines can be specified with PHP Extra's syntax:
 ```
 ````
 
-[CodeHilite]: code_hilite.html
+[CodeHilite]: code_hilite.md
 [Pygments]: http://pygments.org/
-[colon]: code_hilite.html#colons
+[colon]: code_hilite.md#colons
 
 ## Usage
 
diff --git a/docs/extensions/index.md b/docs/extensions/index.md
index cbfdab6..26b117b 100644
--- a/docs/extensions/index.md
+++ b/docs/extensions/index.md
@@ -44,9 +44,10 @@ Extension                            | Entry Point    | Dot Notation
 &nbsp; &nbsp; [Fenced Code Blocks][] | `fenced_code`  | `markdown.extensions.fenced_code`
 &nbsp; &nbsp; [Footnotes][]          | `footnotes`    | `markdown.extensions.footnotes`
 &nbsp; &nbsp; [Tables][]             | `tables`       | `markdown.extensions.tables`
-&nbsp; &nbsp; [Smart Strong][]       | `smart_strong` | `markdown.extensions.smart_strong`
 [Admonition][]                       | `admonition`   | `markdown.extensions.admonition`
 [CodeHilite][]                       | `codehilite`   | `markdown.extensions.codehilite`
+[Legacy Attributes][]                | `legacy_attr`  | `markdown.extensions.legacy_attr`
+[Legacy Emphasis][]                  | `legacy_em`    | `markdown.extensions.legacy_em`
 [Meta-Data]                          | `meta`         | `markdown.extensions.meta`
 [New Line to Break]                  | `nl2br`        | `markdown.extensions.nl2br`
 [Sane Lists]                         | `sane_lists`   | `markdown.extensions.sane_lists`
@@ -61,9 +62,10 @@ Extension                            | Entry Point    | Dot Notation
 [Fenced Code Blocks]: fenced_code_blocks.md
 [Footnotes]: footnotes.md
 [Tables]: tables.md
-[Smart Strong]: smart_strong.md
 [Admonition]: admonition.md
 [CodeHilite]: code_hilite.md
+[Legacy Attributes]: legacy_attr.md
+[Legacy Emphasis]: legacy_em.md
 [Meta-Data]: meta_data.md
 [New Line to Break]: nl2br.md
 [Sane Lists]: sane_lists.md
diff --git a/docs/extensions/legacy_attr.md b/docs/extensions/legacy_attr.md
new file mode 100644
index 0000000..0066867
--- /dev/null
+++ b/docs/extensions/legacy_attr.md
@@ -0,0 +1,59 @@
+title: Legacy Attributes Extension
+
+# Legacy Attributes
+
+## Summary
+
+The Legacy Attributes extension restores Python-Markdown's original attribute
+setting syntax. Older versions of Python Markdown (prior to 3.0) included
+built-in and undocumented support for defining attributes on elements. Most
+users have never made use of the syntax and it has been deprecated in favor of
+[Attribute Lists](attr_list.md). This extension restores the legacy behavior for
+users who have existing documents which use the syntax.
+
+## Syntax
+
+Attributes are defined by including the following within the element you wish to
+assign the attributes to:
+
+```md
+{@key=value}
+```
+
+For example, to define a class to a paragraph:
+
+```md
+A paragraph with the attribute defined {@class=foo}anywhere within.
+```
+
+Which results in the following output:
+
+```html
+<p class="foo">A paragraph with the attribute defined anywhere within.</p>
+```
+
+The same applies for inline elements:
+
+```md
+Some *emphasized{@id=bar}* text.
+```
+
+```html
+<p>Some <em id="bar">emphasized</em> text.</p>
+
+You can also define attributes in images:
+
+```md
+![Alt text{@id=baz}](path/to/image.jpg)
+```
+
+```html
+<p><img alt="Alt text" id="baz" src="path/to/image.jpg" /></p>
+```
+
+## Usage
+
+See [Extensions](index.md) for general extension usage. Use `legacy_attr` as the
+name of the extension.
+
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/legacy_em.md b/docs/extensions/legacy_em.md
new file mode 100644
index 0000000..aad1e50
--- /dev/null
+++ b/docs/extensions/legacy_em.md
@@ -0,0 +1,25 @@
+title: Legacy EM Extension
+
+# Legacy EM
+
+## Summary
+
+The Legacy EM extension restores Markdown's original behavior for emphasis and
+strong syntax when using underscores.
+
+By default Python-Markdown treats `_connected_words_` intelligently by
+recognizing that mid-word underscores should not be used for emphasis. In other
+words, by default, that input would result in this output:
+`<em>connected_words</em>`.
+
+However, that behavior is not consistent with the original rules or the behavior
+of the reference implementation. Therefore, this extension can be used to better
+match the reference implementation. With the extension enabled, the above input
+would result in this output: `<em>connected</em>words_`.
+
+## Usage
+
+See [Extensions](index.md) for general extension usage. Use `legacy_em` as the
+name of the extension.
+
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/sane_lists.md b/docs/extensions/sane_lists.md
index 81f8d84..6d364c1 100644
--- a/docs/extensions/sane_lists.md
+++ b/docs/extensions/sane_lists.md
@@ -66,6 +66,27 @@ With this extension the above will result in the following output:
 </ol>
 ```
 
+Sane lists also recognize the number used in ordered lists. Given the following
+list:
+
+```md
+4. Apples
+5. Oranges
+6. Pears
+```
+
+By default markdown will ignore the fact that the first line started
+with item number "4" and the HTML list will start with a number "1".
+This extension will result in the following HTML output:
+
+```html
+<ol start="4">
+  <li>Apples</li>
+  <li>Oranges</li>
+  <li>Pears</li>
+</ol>
+```
+
 In all other ways, Sane Lists should behave as normal Markdown lists.
 
 Usage
diff --git a/docs/extensions/smart_strong.md b/docs/extensions/smart_strong.md
deleted file mode 100644
index 65c88d6..0000000
--- a/docs/extensions/smart_strong.md
+++ /dev/null
@@ -1,36 +0,0 @@
-title: Smart Strong Extension
-
-Smart_Strong
-============
-
-Summary
--------
-
-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.
-
-[smart_emphasis]: ../reference.md#smart_emphasis
-
-Example
--------
-
-```pycon
->>> import markdown
->>> markdown.markdown('Text with double__underscore__words.', extensions=['smart_strong'])
-u'<p>Text with double__underscore__words.</p>'
->>> markdown.markdown('__Strong__ still works.', extensions=['smart_strong'])
-u'<p><strong>Strong</strong> still works.</p>'
->>> markdown.markdown('__this__works__too__.', extensions=['smart_strong'])
-u'<p><strong>this__works__too</strong>.</p>'
-```
-
-Usage
------
-
-See [Extensions](index.md) for general extension usage. Use `smart_strong` as
-the name of the extension.
-
-This extension does not accept any special configuration options.
diff --git a/docs/extensions/smarty.md b/docs/extensions/smarty.md
index 109d78c..0efbe4a 100644
--- a/docs/extensions/smarty.md
+++ b/docs/extensions/smarty.md
@@ -48,7 +48,7 @@ extension_configs = {
     has been known to do.
 
 [SmartyPants]: http://pythonhosted.org/smartypants/
-[CodeHilite]: code_hilite.html
+[CodeHilite]: code_hilite.md
 
 Usage
 -----