A Python package/CLI to format and lint Python code blocks within Markdown files. Specifically designed for Markdown files used with mkdocs-material.

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

Use pipx:

pipx install md-snakeoil

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

snakeoil path/to/directory

That's it! 🚀

Note

If, your using uv, install it with uv tool install md-snakeoil

Command Line Interface

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

Help

snakeoil --help

 Usage: snakeoil [OPTIONS] [PATH] COMMAND [ARGS]...                                                                                              
                                                                                                                                                 
 Format and lint Python code blocks in Markdown files.

╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   path      [PATH]  File or directory to format [default: None]                                                                               │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --line-length               INTEGER  Maximum line length for the formatted code [default: 79]                                                 │
│ --rules                     TEXT     Ruff rules to apply (comma-separated) [default: I,W]                                                     │
│ --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

Formatting files... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01
         Results for tests\examples
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Directory      ┃ File            ┃ Status ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ tests\examples │ indentation.md  │ ✅     │
│ tests\examples │ info_strings.md │ ✅     │
│ tests\examples │ test.md         │ ✅     │
└────────────────┴─────────────────┴────────┘
All 3 files formatted successfully. ✨