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.

The data can be written row by row under rows:

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

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

or column by column under columns:

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

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

Both render as:

• header is optional. It maps column keys to a display name, or to a mapping with name and align (left, center or right). Configured columns come first; other keys found in the data follow in order of appearance.
• Use either rows or columns per block, not both. In column-first data, shorter columns are padded with empty cells.

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