Mdformat GFM

1.0.0 · active · verified Sun Apr 12

Mdformat-gfm is an mdformat plugin that extends the core mdformat library to support GitHub Flavored Markdown (GFM) syntax extensions, including tables, task list items, strikethroughs, and autolinks. It allows mdformat to properly format Markdown files that utilize these GFM features. The library is currently at version 1.0.0 and typically releases new versions in sync with its parent library, mdformat.

Warnings

breaking mdformat-gfm, via its dependency on mdformat 1.0.0, no longer supports Python 3.9. Users must upgrade to Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or later.
deprecated The separate `mdformat-tables` plugin has been deprecated. Table formatting support is now included directly within `mdformat-gfm`. Users should migrate from `mdformat-tables` to `mdformat-gfm` for table support.
Fix: Remove `mdformat-tables` and ensure `mdformat-gfm` is installed. Use the `gfm` extension for full GFM (including tables) support.
gotcha There is no guarantee for a stable Markdown formatting style across `mdformat` versions (which `mdformat-gfm` depends on). Formatting output might change in minor or patch releases.
Fix: It is highly recommended to pin the `mdformat` and `mdformat-gfm` dependencies to exact versions in your project to ensure consistent formatting results.
gotcha Combining `mdformat-gfm` with other `mdformat` plugins (e.g., `mdformat-admon`) can sometimes lead to dependency conflicts, particularly with underlying `mdit-py-plugins` versions.
Fix: If conflicts arise, try updating all `mdformat` related plugins to their latest compatible versions or review the dependency trees for conflicting `markdown-it-py` or `mdit-py-plugins` requirements.
gotcha The `mdformat-gfm` plugin allows configuration of 'compact tables' via a `--compact-tables` CLI option or `compact_tables` TOML boolean. When enabled, this strips extra spaces used for column alignment in GFM tables.
Fix: If precise table alignment is desired, ensure `--compact-tables` is not used in the CLI or `compact_tables` is set to `false` in your TOML configuration.

Install

pip install mdformat mdformat-gfm Install for general library usage
pipx install mdformat && pipx inject mdformat mdformat-gfm Install for CLI usage (recommended for formatters)

Imports

mdformat
```
import mdformat
```
mdformat-gfm is an auto-discovered plugin; its functionality is accessed through the mdformat API by specifying extensions.

Quickstart

This quickstart demonstrates how to use `mdformat` with the `mdformat-gfm` plugin via its Python API. The `mdformat-gfm` plugin is automatically loaded by `mdformat` once installed, and its GFM capabilities are enabled by passing `extensions=['gfm']` to `mdformat.text()` or `mdformat.file()`.

import mdformat

unformatted_gfm = """
# My GFM Document

- [ ] Task list item
- [x] Another task

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |

This is a ~~strikethrough~~ text.
"""

# To format a string with GFM support:
formatted_text = mdformat.text(unformatted_gfm, extensions=['gfm'])
print(formatted_text)

# To format a file in place:
# with open('my_gfm_file.md', 'w') as f:
#     f.write(unformatted_gfm)
# mdformat.file('my_gfm_file.md', extensions=['gfm'])
# with open('my_gfm_file.md', 'r') as f:
#     print(f.read())

view raw JSON →