CommonMark compliant Markdown formatter
Project description
mdformat
CommonMark compliant Markdown formatter
Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files. Mdformat is a Unix-style command-line tool as well as a Python library.
The features/opinions of the formatter include:
- Strip trailing and leading whitespace
- Always use ATX style headings
- Consistent indentation for contents of block quotes and list items
- Reformat reference links as inline links
- Reformat indented code blocks as fenced code blocks
- Separate blocks with a single empty line (an exception being tight lists where the separator is a single newline character)
- End the file in a single newline character
- Use
1.as the ordered list marker if possible, also for noninitial list items
Mdformat by default will not change word wrapping. The rationale for this is to support techniques like One Sentence Per Line and Semantic Line Breaks.
NOTE: The formatting style produced by mdformat may change in each version. It is recommended to pin mdformat dependency version.
Installing
pip install mdformat
Command line usage
Format files
Format files README.md and CHANGELOG.md in place
mdformat README.md CHANGELOG.md
Format .md files in current working directory recursively
mdformat .
Read Markdown from standard input until EOF.
Write formatted Markdown to standard output.
mdformat -
Check formatting
mdformat --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.
Python API usage
Format text
import mdformat
unformatted = "\n\n# A header\n\n"
formatted = mdformat.text(unformatted)
assert formatted == "# A header\n"
Format a file
Format file README.md in place:
import mdformat
# Input filepath as a string...
mdformat.file("README.md")
# ...or a pathlib.Path object
import pathlib
filepath = pathlib.Path("README.md")
mdformat.file(filepath)
Usage as a pre-commit hook
mdformat can be used as a pre-commit hook.
Add the following to your project's .pre-commit-config.yaml to enable this:
- repo: https://github.com/executablebooks/mdformat
rev: 0.3.0 # Use the ref you want to point at
hooks:
- id: mdformat
Code formatter plugins
Mdformat features a plugin system to support formatting of Markdown code blocks where the coding language has been labeled.
For instance, if mdformat-black plugin is installed in the environment,
mdformat CLI will automatically format Python code blocks with Black.
For stability, mdformat Python API behavior will not change simply due to a plugin being installed. Code formatters will have to be explicitly enabled in addition to being installed:
import mdformat
unformatted = "```python\n'''black converts quotes'''\n```\n"
# Pass in `codeformatters` here! It is an iterable of coding languages
# that should be formatted
formatted = mdformat.text(unformatted, codeformatters={"python"})
assert formatted == '```python\n"""black converts quotes"""\n```\n'
Read the contribution guide if you wish to implement a new code formatter plugin.
Existing formatter plugins
| Plugin | Supported languages |
|---|---|
| mdformat-black | python |
| mdformat-config | json, toml, yaml |
| mdformat-beautysh | bash, sh |
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mdformat-0.3.0.tar.gz.
File metadata
- Download URL: mdformat-0.3.0.tar.gz
- Upload date:
- Size: 14.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.10 CPython/3.6.9 Linux/5.4.0-47-generic
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ff6f243b6c0f1f188fca8ec8b7346262caa25bddb3e51a62cf88334cea9837a4 |
|
| MD5 | 9114b307fda126b7ec489833efa1e4d5 |
|
| BLAKE2b-256 | 9299ffd73fc9e2152544a311de76cb4503f765a3fd8c457fece9c28e0e826aa1 |
File details
Details for the file mdformat-0.3.0-py3-none-any.whl.
File metadata
- Download URL: mdformat-0.3.0-py3-none-any.whl
- Upload date:
- Size: 14.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.10 CPython/3.6.9 Linux/5.4.0-47-generic
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 70f3e0a17e4d0758b87d92148fd13a06c0dbc1ff5e94cef11015bc5a781f229d |
|
| MD5 | 014b7df1e9372970bbf4ce459edf143c |
|
| BLAKE2b-256 | bb8ac587b8c9c8f3678438eb948bc49ce85bb85e1047106cd4d49c72ee7cc4a4 |
