Metadata-Version: 2.4
Name: pymd-gadgets
Version: 0.1.0
Summary: Small Python-Markdown extensions: lists without blank lines and tables written in YAML. Works great with MkDocs.
Keywords: markdown,python-markdown,mkdocs,extension,yaml,table,lists
Author: Johannes Piermeier
Author-email: Johannes Piermeier <pierm.jo+git@proton.me>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Dist: markdown>=3.7
Requires-Dist: pyyaml>=6.0.1
Requires-Python: >=3.10
Project-URL: Homepage, https://gitlab.com/jopiermeier/pymd_gadgets
Project-URL: Source, https://gitlab.com/jopiermeier/pymd_gadgets
Project-URL: Issues, https://gitlab.com/jopiermeier/pymd_gadgets/-/issues
Project-URL: Changelog, https://gitlab.com/jopiermeier/pymd_gadgets/-/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# pymd-gadgets

Small [Python-Markdown](https://python-markdown.github.io/) extensions that make Markdown more pleasant to write.
They work anywhere Python-Markdown is used, including [MkDocs](https://www.mkdocs.org/) 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

```bash
pip install pymd-gadgets
```

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

## Usage

### MkDocs

```yaml
# 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

```python
import markdown

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

You can also pass extension instances:

```python
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. 

```markdown
Pros:
- Fast
- Simple
```

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

With `compact_lists` enabled, it renders as expected:

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

It follows the [CommonMark](https://spec.commonmark.org/) 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.

````markdown
```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:

| Tool | Purpose | license |
| ---: | :--- | :--- |
| [MkDocs](https://www.mkdocs.org/) | Static site generator | BSD-2-Clause |
| `pymd-gadgets` | Markdown extensions | MIT |

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

## Development

```bash
uv sync
uv run pytest
```

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

## License

[MIT](https://gitlab.com/jopiermeier/pymd_gadgets/-/blob/main/LICENSE)
