Metadata-Version: 2.4
Name: md_kx
Version: 1.0.0
Summary: CommonMark compliant Markdown formatter
Author-email: Taneli Hukkinen <hukkin@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hukkin/mdformat
Keywords: md_kx,markdown,commonmark,formatter,pre-commit
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown-it-py<5,>=1
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Dynamic: license-file

<div align="center">

[![Build Status](https://github.com/TuTouPower/md_kx/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/TuTouPower/md_kx/actions/workflows/tests.yaml)
[![PyPI version](https://img.shields.io/pypi/v/md-kx)](https://pypi.org/project/md-kx)

# ![md_kx](assets/logo.svg)

> CommonMark compliant Markdown formatter

</div>

<!-- start mini-description -->

Md_kx is an opinionated Markdown formatter
that can be used to enforce a consistent style in Markdown files.
Md_kx is a Unix-style command-line tool as well as a Python library.

<!-- end mini-description -->

<!-- start installing -->

## Installing

Install with [CommonMark](https://spec.commonmark.org/current/) support:

```bash
pipx install md_kx
```

<!-- end installing -->

For the full user guide (new fork features, config file, Python API,
pre-commit hook), see [`docs/guides/usage.md`](docs/guides/usage.md);
for the formatting style reference, see [`docs/guides/style.md`](docs/guides/style.md).

<!-- start cli-usage -->

## Command line usage

### Format files

Format files `README.md` and `CHANGELOG.md` in place

```bash
md_kx README.md CHANGELOG.md
```

Format `.md` files in current working directory recursively

```bash
md_kx .
```

Read Markdown from standard input until `EOF`.
Write formatted Markdown to standard output.

```bash
md_kx -
```

### Check formatting

```bash
md_kx --check README.md CHANGELOG.md
```

This will not apply any changes to the files.
If a file is not properly formatted, the exit code will be non-zero.

### Options

```console
foo@bar:~$ md_kx --help
usage: md_kx [-h] [--check] [--no-validate] [--version] [--commit] [--number]
             [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}]
             [--indent-width INTEGER] [--table-mode {compact,spaced,pad}]
             [--exclude PATTERN] [--extensions EXTENSION]
             [--codeformatters LANGUAGE]
             [paths ...]

CommonMark compliant Markdown formatter

positional arguments:
  paths                 files to format

options:
  -h, --help            show this help message and exit
  --check               do not apply changes to files
  --no-validate         do not validate that the rendered HTML is consistent
  --version             show program's version number and exit
  --commit              print the dev build commit id ("unknown" for PyPI
                        builds) and exit
  --number              apply consecutive numbering to ordered lists
  --wrap {keep,no,INTEGER}
                        paragraph word wrap mode (default: keep)
  --end-of-line {lf,crlf,keep}
                        output file line ending mode (default: lf)
  --indent-width INTEGER
                        unified indentation width for nested lists (default:
                        marker-aligned)
  --table-mode {compact,spaced,pad}
                        table output style: compact (no padding), spaced (one
                        space each side), pad (column-aligned) (default:
                        spaced)
  --exclude PATTERN     exclude files that match the Unix-style glob pattern
                        (multiple allowed)
  --extensions EXTENSION
                        require and enable an extension plugin (multiple
                        allowed) (use `--no-extensions` to disable) (default:
                        all enabled)
  --codeformatters LANGUAGE
                        require and enable a code formatter plugin (multiple
                        allowed) (use `--no-codeformatters` to disable)
                        (default: all enabled)
```

The `--exclude` option is only available on Python 3.13+.

<!-- end cli-usage -->

<!-- start faq -->

## Frequently Asked Questions

### Why does md_kx backslash escape special syntax specific to MkDocs / Hugo / Obsidian / GitHub / some other Markdown engine?

Md_kx is a CommonMark formatter.
It doesn't have out-of-the-box support for syntax other than what is defined in [the CommonMark specification](https://spec.commonmark.org/current/).

The custom syntax that these Markdown engines introduce typically redefines the meaning of
angle brackets, square brackets, parentheses, hash character — characters that are special in CommonMark.
Md_kx often resorts to backslash escaping these characters to ensure its formatting changes never alter a rendered document.

Additionally some engines, namely MkDocs,
[do not support](https://github.com/mkdocs/mkdocs/issues/1835) CommonMark to begin with,
so incompatibilities are unavoidable.

Luckily md_kx is extensible by plugins.
For many Markdown engines you'll find support by searching
[the plugin docs](https://github.com/topics/mdformat)
or [mdformat GitHub topic](https://github.com/topics/mdformat).

You may also want to consider a documentation generator that adheres to CommonMark as its base syntax
e.g. [mdBook](https://rust-lang.github.io/mdBook/)
or [Sphinx with Markdown](https://www.sphinx-doc.org/en/master/usage/markdown.html).

### Why not use [Prettier](https://github.com/prettier/prettier) instead?

Md_kx is pure Python code!
Python is pre-installed on macOS and virtually any Linux distribution,
meaning that typically little to no additional installations are required to run md_kx.
This argument also holds true when using together with
[pre-commit](https://github.com/pre-commit/pre-commit) (also Python).
Prettier on the other hand requires Node.js/npm.

Prettier suffers from
[numerous](https://github.com/prettier/prettier/issues?q=is%3Aopen+label%3Alang%3Amarkdown+label%3Atype%3Abug+)
bugs,
many of which cause changes in Markdown AST and rendered HTML.
Many of these bugs are a consequence of using
[`remark-parse`](https://github.com/remarkjs/remark/tree/main/packages/remark-parse)
v8.x as Markdown parser which,
according to the author themselves,
is [inferior to markdown-it](https://github.com/remarkjs/remark/issues/75#issuecomment-143532326) used by md_kx.
`remark-parse` v9.x is advertised as CommonMark compliant
and presumably would fix many of the issues,
but is not used by Prettier (v3.3.3) yet.

Prettier (v3.3.3), being able to format many languages other than Markdown,
is a large package with 73 direct dependencies
(md_kx only has one in Python 3.11+).
This can be a disadvantage in many environments,
one example being size optimized Docker images.

Md_kx's parser extension plugin API allows not only customization of the Markdown specification in use,
but also advanced features like [automatic table of contents generation](https://github.com/hukkin/mdformat-toc).
Also provided is a code formatter plugin API enabling integration of embedded code formatting for any programming language.

### What's wrong with the md_kx logo? It renders incorrectly and is just terrible in general.

Nope, the logo is actually pretty great – you're terrible.
The logo is more a piece of art than a logo anyways,
depicting the horrors of poorly formatted text documents.
I made it myself!

That said, if you have any graphic design skills and want to contribute a revised version, a PR is more than welcome 😄.

<!-- end faq -->
