{"id":2585,"library":"mdx-truly-sane-lists","title":"mdx-truly-sane-lists","description":"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.","status":"active","version":"1.3","language":"en","source_language":"en","source_url":"https://github.com/radude/mdx_truly_sane_lists","tags":["markdown","extension","lists","python-markdown"],"install":[{"cmd":"pip install mdx-truly-sane-lists","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This is a Python-Markdown extension and requires the core Markdown library to function.","package":"Markdown","optional":false}],"imports":[{"note":"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.","symbol":"mdx_truly_sane_lists","correct":"from markdown import markdown\nmarkdown(text, extensions=['mdx_truly_sane_lists'])"}],"quickstart":{"code":"from markdown import markdown\n\n# Basic usage with default config (nested_indent: 2, truly_sane: True)\ntext_basic = \"\"\"\n- Item 1\n  - Nested Item 1\n    - Double Nested\n- Item 2\n\"\"\"\nhtml_basic = markdown(text_basic, extensions=['mdx_truly_sane_lists'])\nprint(\"Basic Render:\\n\", html_basic)\n\n# With explicit config for customization\ntext_config = \"\"\"\n1. Ordered Item 1\n   1. Nested Ordered Item 1\n2. Ordered Item 2\n\"\"\"\nhtml_config = markdown(\n    text_config,\n    extensions=['mdx_truly_sane_lists'],\n    extension_configs={\n        'mdx_truly_sane_lists': {\n            'nested_indent': 4, # Custom indent, default is 2\n            'truly_sane': True # Fixes linebreaks/paragraphs, default is True\n        }\n    }\n)\nprint(\"\\nConfigured Render:\\n\", html_config)","lang":"python","description":"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."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":"mdx-truly-sane-lists < 1.3 when used with Python-Markdown >= 3.4"},{"fix":"Upgrade mdx-truly-sane-lists to version 1.2 or newer.","message":"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.","severity":"breaking","affected_versions":"mdx-truly-sane-lists < 1.2 when used with Python-Markdown >= 3.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions (inherent behavior interacting with default Markdown parsing)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (inherent design feature)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}