mdformat-simple-breaks

An mdformat plugin to render thematic breaks using three dashes

---

instead of 70 underscores

________________________________________________________________________________

Install

Install with:

pip install mdformat-simple-breaks

Usage as a pre-commit hook

Add the following to your .pre-commit-config.yaml:

- repo: https://github.com/executablebooks/mdformat
  rev: 1.0.0  # Use the ref you want to point at
  hooks:
    - id: mdformat
      additional_dependencies:
        - mdformat-simple-breaks

Plugin rationale

The CommonMark specification states that thematic breaks, which are to be rendered as horizontal rules <hr>, should be coded as:

A line consisting of optionally up to three spaces of indentation, followed by a sequence of three or more matching -, _, or * characters, each followed optionally by any number of spaces or tabs

As a result, most of the Markdown guides and cheat sheets show a line made of three dash symbols as an example of a thematic break, and therefore this likely to be the format which Markdown writers are most used to type.

On the other hand, plain mdformat renders these thematic breaks as a line of 70 consecutive underscore characters. This is an explicit style decision that is not going to be reverted and for which no configuration will be added.

As a result, this plugin has been created to offer the option to render the thematic breaks using the common three dash style when preferred.