md-snakeoil 0.1.9

Format and lint Python code blocks within Markdown files. Usable as CLI, pre-commit hook or Python package.

md-snakeoil is built on the awesome ruff formatter and linter and helps you to keep your Markdown files looking sharp. 🤙🏽

before vs. after

Quickstart

With uv install it as a tool:

uv tool install md-snakeoil

Format and lint Markdown files within a directory (recursively):

snakeoil path/to/directory

That's it! 🚀

pre-commit hook

To run md-snakeoil with pre-commit add following to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/JakobKlotz/md-snakeoil
    rev: v0.1.9
    hooks:
      - id: snakeoil

Command Line Interface

The package provides a command-line interface (CLI) using typer.

Help

snakeoil --help

 Usage: snakeoil [OPTIONS] [PATH]                                                                                            
                                                                                                                                                 
 Format & lint Markdown files. Either a single file or all files in a directory,

╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   path      [PATH]  File or directory to process                                                                                              │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --line-length               INTEGER  Maximum line length for the formatted code [default: 79]                                                 │
│ --rules                     TEXT     Ruff rules to apply (comma-separated) [default: I,W]                                                     │
│ --check --no-check                   Check if files would be reformatted without writing changes [default: no-check]                          │
│ --install-completion                 Install completion for the current shell.                                                                │
│ --show-completion                    Show completion for the current shell, to copy it or customize the installation.                         │
│ --help                               Show this message and exit.                                                                              │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

By default, the line length is set to 79 characters, and the Ruff rules W and I are enabled. You can change these defaults using the --line-length and --rules options.

Single Markdown

snakeoil path/to/file.md

Formatting all files in a directory

snakeoil path/to/directory

This will recursively format and lint the Python code blocks in all Markdown files within path/to/directory.

For example, format the example files within the tests/ directory (of this repository):

> snakeoil tests/examples

Formatted: tests\examples\indentation.md
Formatted: tests\examples\info_strings.md
Formatted: tests\examples\test.md
3 formatted, 0 already formatted.