MDWrap

Table of Contents

• Overview
• Pre-commit Hook
• Installation
• Usage
  • Arguments
• Limitations
• Alternatives
• Contributing
  • Development
  • Testing
  • Linting
  • Releasing
• References

Overview

mdwrap is a Python package that wraps text in Markdown files to a specified width. It also implements basic newline formatting and trailing whitespace removal. This package was built for compatibility with Material for MKDocs.

The motivation for this project was to have a lightweight package with no external dependencies that works well with Material for MkDocs for wrapping and basic formatting of Markdown files.

Pre-commit Hook

You can use mdwrap as a pre-commit hook to automatically wrap your Markdown files. To do so, add the following to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/swiss-ai-center/mdwrap
      rev: 0.2.4
      hooks:
        - id: mdwrap
          args: [--print-width, "80", --fmt]

Installation

pip install git+https://github.com/swiss-ai-center/[email protected]

Usage

mdwrap [-h] [--print-width PRINT_WIDTH] [--fmt] [--unwrap] [--check]
       [--ignore IGNORE] [--ignore-extend IGNORE_EXTEND] [--version]
       targets [targets ...]

# To format (wrap) a file:
mdwrap file.md
# To format (wrap + remove trailing newline + whitespace) a file:
mdwrap --fmt file.md
# To check (wrap) a file:
mdwrap --check file.md
# To check (wrap + remove trailing newline + whitespace) a file:
mdwrap --fmt --check file.md

Arguments

Argument	Description	Default
-h, --help	Show the help message and exit
-v, --version	Show the version and exit
--print-width	Maximum width of a line	80
--fmt	Format files	False
--unwrap	Unwrap files	False
--check	Check if files are formatted	False
-i, --ignore	Ignore files matching this glob pattern	check with mdwrap -h
-I, --ignore-extend	Extend the default ignore pattern with this glob pattern	None
targets	Files or folders of files to format

Limitations

One limitation of mdwrap is that it does not yet support wrapping quote blocks.

Alternatives

• mdformat is a Python package that formats Markdown files. It is more feature-rich than mdwrap however it does not support Material for MkDocs admonitions entirely.
• prettier is a powerful code formatter that supports Markdown. It's only downside is that it needs a node environment to run.

Contributing

Development

Create and enable a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install the development dependencies:

pip install .

Install the pre-commit hooks:

pre-commit install

Testing

To run the tests:

pytest

Linting

To lint the code:

pre-commit run -a

Releasing

1. Make sure to first update the versions in this file.
2. Update the CHANGELOG.
3. Next, release a new version by running the following:

# Bump the version in pyproject.toml
sed -i 's/version = ".*"/version = "0.x.y"/' pyproject.toml
# Create a new tag
git tag <version> main
# Push the tag
git push origin <version>

4. Update the changes in the new GitHub release.
5. Finally, update the version in the pre-commit hook in .pre-commit-config.yaml.

References

This project is built with the following tools:

• pre-commit
• pytest
• flake8
• black

It is also inspired by the following projects:

• black
• prettier