I’d like to share another tool that I’m developing: md-snakeoil – a CLI tool that brings the power of code formatting and linting to your Markdown files. If you’ve ever struggled with inconsistent Python code blocks in your documentation, this tool is for you.
What does it do?
md-snakeoil is a tool that formats and lints Python code blocks within Markdown files. Built on top of the excellent ruff formatter and linter, it ensures your documentation code examples are always clean and consistent.
Why?
I’ve written it for a specific use case: Primarily, I’m writing course material for my students within Markdown and publish it with mkdocs-material, so I wanted a way to ensure all Python code blocks are formatted correctly and follow best practices. With this tool, I can simply format multiple files with a single command.
Nevertheless, md-snakeoil can be used in any project that requires consistent Python code formatting in Markdown. Hence, I’ve open-sourced it, so hopefully it will be useful for others as well!
Key Features
- Simple CLI
- Automatic formatting
- Intelligent linting
- Bulk processing of directories
Where to use it?
It’s perfect for:
- Documentation projects using mkdocs/mkdocs-material or similar generators
- Technical blogs and tutorials with Python code examples
- … or any other project where code consistency in documentation matters
Getting Started
md-snakeoil is published on PyPI. Installation is straightforward with uv:
uv tool install md-snakeoilFormat all Markdown files in a directory:
snakeoil directory/pathThat’s it – just two commands! 🚀
Wrap-up
The project is open source and designed for developers and technical writers who care about documentation quality.
Ready to make your documentation shine? Check out the project on GitHub!
References
The project was made possible with the help of several amazing tools ❤️