From 833574a9da27874614f7184f85f7993a539f3df1 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Thu, 2 Aug 2018 14:51:16 -0400 Subject: Update 3.0 release notes And other docs cleanup. --- docs/extensions/api.md | 164 +++++++++++++--------------------- docs/extensions/code_hilite.md | 9 ++ docs/extensions/extra.md | 1 - docs/extensions/fenced_code_blocks.md | 4 +- docs/extensions/index.md | 6 +- docs/extensions/legacy_attr.md | 59 ++++++++++++ docs/extensions/legacy_em.md | 25 ++++++ docs/extensions/sane_lists.md | 21 +++++ docs/extensions/smart_strong.md | 36 -------- docs/extensions/smarty.md | 2 +- 10 files changed, 183 insertions(+), 144 deletions(-) create mode 100644 docs/extensions/legacy_attr.md create mode 100644 docs/extensions/legacy_em.md delete mode 100644 docs/extensions/smart_strong.md (limited to 'docs/extensions') 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 `` 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 `` 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), '`) 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, '>> 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', 'A paragraph with the attribute defined anywhere within.

+``` + +The same applies for inline elements: + +```md +Some *emphasized{@id=bar}* text. +``` + +```html +

Some emphasized text.

+ +You can also define attributes in images: + +```md +![Alt text{@id=baz}](path/to/image.jpg) +``` + +```html +

Alt text

+``` + +## 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: +`connected_words`. + +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: `connectedwords_`. + +## 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: ``` +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 +
    +
  1. Apples
    2. +
  2. Oranges
    3. +
  3. Pears
    4. +
+``` + 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'

Text with double__underscore__words.

' ->>> markdown.markdown('__Strong__ still works.', extensions=['smart_strong']) -u'

Strong still works.

' ->>> markdown.markdown('__this__works__too__.', extensions=['smart_strong']) -u'

this__works__too.

' -``` - -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 ----- -- cgit v1.2.1