installation_and_usage.md

Installation and usage

:start-after: <!-- start installing -->
:end-before: <!-- end installing -->

The formatting style produced by mdformat may change in each version.
It is recommended to pin mdformat dependency version.

:start-after: <!-- start cli-usage -->
:end-before: <!-- end cli-usage -->

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)

Options

All formatting style modifying options available in the CLI are also available in the Python API, with equivalent option names:

import mdformat

mdformat.file(
    "FILENAME.md",
    options={
        "number": True,  # switch on consecutive numbering of ordered lists
        "wrap": 60,  # set word wrap width to 60 characters
    }
)

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.7.15  # Use the ref you want to point at
  hooks:
  - id: mdformat
    # Optionally add plugins
    additional_dependencies:
    - mdformat-gfm
    - mdformat-black