mdx-truly-sane-lists

1.3 · active · verified Fri Apr 10

mdx-truly-sane-lists is an extension for Python-Markdown that aims to make lists behave more predictably. It provides features like custom indents for nested lists and fixes for messy linebreaks and paragraphs within lists. The current version is 1.3, released in 2022, with previous major updates in 2018 and 2016, indicating an infrequent release cadence.

Warnings

breaking Incompatibility with Python-Markdown 3.4+ prior to mdx-truly-sane-lists v1.3. Older versions of this extension would fail to load with Python-Markdown versions 3.4 and newer, resulting in 'Failed loading extension' errors.
Fix: Upgrade mdx-truly-sane-lists to version 1.3 or newer. If an upgrade is not possible, pin the 'Markdown' package dependency to a version less than 3.4 (e.g., `Markdown==3.3.7`).
breaking Incompatibility with Python-Markdown 3.0+ prior to mdx-truly-sane-lists v1.2. Earlier versions of this extension were not compatible with Python-Markdown 3.0 and above.
Fix: Upgrade mdx-truly-sane-lists to version 1.2 or newer.
gotcha Ordered lists not starting at '1' may not render as expected. When used, especially with MkDocs Material, ordered lists that do not explicitly start with `1.` (e.g., `5. Item A`) might not be processed correctly by the extension, potentially overriding Python-Markdown's default `sane_lists` behavior for such cases.
Fix: Ensure ordered lists start from `1.`. For MkDocs users, a workaround involves adding a hook to patch the `TrulySaneOListProcessor` to set `LAZY_OL = False` (refer to GitHub issue #21 for details).
gotcha The extension enforces 'sane lists' behavior, disallowing the mixing of ordered and unordered list items without proper separation. This is an intentional design choice but can be unexpected for users accustomed to more lenient Markdown parsers.
Fix: Always separate different list types (ordered vs. unordered) with a blank line if they are meant to be distinct lists, or maintain a consistent list type within a logical block to avoid unintended merging or rendering issues.

Install

pip install mdx-truly-sane-lists Install with pip

Imports

mdx_truly_sane_lists
```
from markdown import markdown
markdown(text, extensions=['mdx_truly_sane_lists'])
```
The extension is loaded by its string name in the 'extensions' parameter of the markdown function or Markdown class constructor; direct import of classes is uncommon for basic usage.

Quickstart

This quickstart demonstrates how to apply the `mdx-truly-sane-lists` extension to Markdown text using the `markdown` function. It shows both basic usage with default settings and how to provide custom configurations for `nested_indent` and `truly_sane` options.

from markdown import markdown

# Basic usage with default config (nested_indent: 2, truly_sane: True)
text_basic = """
- Item 1
  - Nested Item 1
    - Double Nested
- Item 2
"""
html_basic = markdown(text_basic, extensions=['mdx_truly_sane_lists'])
print("Basic Render:\n", html_basic)

# With explicit config for customization
text_config = """
1. Ordered Item 1
   1. Nested Ordered Item 1
2. Ordered Item 2
"""
html_config = markdown(
    text_config,
    extensions=['mdx_truly_sane_lists'],
    extension_configs={
        'mdx_truly_sane_lists': {
            'nested_indent': 4, # Custom indent, default is 2
            'truly_sane': True # Fixes linebreaks/paragraphs, default is True
        }
    }
)
print("\nConfigured Render:\n", html_config)

view raw JSON →