mdformat-hallmark

An mdformat plugin for compatibility with hallmark, MarkdownStyleGuide and Common Changelog that allows both formatters and linters to simultaneously pass for quality assurance.

Features

• remark-preset-lint-markdown-style-guide style compatibility.
• hallmark style formatting of definitions at end of the document with:
  • blank line seperators
  • keep label casing
  • sort first by semantic version labels
  • sort second by alphanumeric labels

Install

Install with:

pip install mdformat-hallmark

CLI Usage

After installing the plugin, run mdformat for Markdown files including Common Changelog files.

# with extension detected automatically
mdformat README.md CHANGELOG.md

# with extension explicitly required
mdformat --extensions hallmark --extensions tables README.md CHANGELOG.md

Pre-Commit Usage

repos:
  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.19
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-hallmark

for latest developement version:

repos:
  - repo: https://github.com/calgray/mdformat-hallmark
    rev: master
    hooks:
      - id: mdformat

Development

This package utilises flit as the build engine, and tox for test automation.

To install these development dependencies:

pip install tox

To run the tests:

tox

and with test coverage:

tox -e py37-cov

The easiest way to write tests, is to edit tests/fixtures.md

To run the code formatting and style checks:

tox -e py37-pre-commit

or directly

pip install pre-commit
pre-commit run --all

To run the pre-commit hook test:

tox -e py37-hook

Publish to PyPi

Either use flit directly:

pip install flit
flit publish

or trigger the GitHub Action job, by creating a release with a tag equal to the version, e.g. v0.0.1.

Note, this requires generating an API key on PyPi and adding it to the repository Settings/Secrets, under the name PYPI_KEY.