pymd-gadgets

Small Python-Markdown extensions that make Markdown more pleasant to write. They work anywhere Python-Markdown is used, including MkDocs and Material for MkDocs.

• compact_lists: start a list right after a line of text, without a blank line in between.
• yamltable: write tables as YAML instead of hand-aligning pipes.

Installation

pip install pymd-gadgets

Requires Python 3.10+. Installs Markdown and PyYAML as dependencies.

Usage

MkDocs

# mkdocs.yml
markdown_extensions:
  - tables            # needed by yamltable
  - compact_lists
  - yamltable

The full module paths pymd_gadgets.compact_lists and pymd_gadgets.yamltable work as well.

Python

import markdown

html = markdown.markdown(
    text,
    extensions=["tables", "compact_lists", "yamltable"],
)

You can also pass extension instances:

from pymd_gadgets import CompactListsExtension, YamlTableExtension

markdown.markdown(text, extensions=["tables", CompactListsExtension(), YamlTableExtension()])

compact_lists

Python-Markdown needs a blank line between a paragraph and a list.

Pros:
- Fast
- Simple

By default, this renders as a single paragraph: Pros: - Fast - Simple.

With compact_lists enabled, it renders as expected:

<p>Pros:</p>
<ul>
<li>Fast</li>
<li>Simple</li>
</ul>

It follows the CommonMark rules for lists that may interrupt a paragraph:

• -, * and + bullet lists and ordered lists starting at 1. or 1) are recognized. A line such as 2024. was a good year stays paragraph text.
• Multi-line items, nested lists and lazy continuation lines stay part of the same list, so the list stays tight.
• Content inside fenced code blocks (``` or ~~~) is left alone.

yamltable

Add a #| yamltable line to a fenced yaml block (usually the first line). It is replaced with a Markdown table. The tables extension must be enabled to render the result.

```yaml
#| yamltable
columns:
  tool:
    name: Tool
    align: right
  use: Purpose

entries:
  - tool: "[MkDocs](https://www.mkdocs.org/)"
    use: Static site generator
    license: BSD-2-Clause
  - tool: "`pymd-gadgets`"
    use: Markdown extensions
    license: MIT
```

renders as:

Blocks without the marker are rendered as ordinary YAML code blocks.

Development

uv sync
uv run pytest

Tests are driven by fixture files in tests/fixtures/, each with an --- input --- and an --- expected --- section.

License

MIT