I have some strong opinions about how Markdown should look. Liberal line breaks everywhere. ATX headers with exactly one space after the #. Consistent list indentation using tabs. Tables that are properly aligned. And on and on. So I made Markdown Fixup (md-fixup).
I just wanted a tool to fix my own Markdown files up to match these preferences. But then I thought, maybe someone else out there has the same opinions, or at least could be swayed to think they were good ideas? So I decided to make it available to the world, just in case anyone’s tastes matched mine.
md-fixup is a comprehensive markdown linter and formatter that performs 27 different normalization and formatting rules. It solves some common issues you might run into with “it works in X.app but not in Y” by standardizing on a consistent set of rules.
I considered building this functionality directly into my Apex project, but I determined it was feature bloat and made more sense as a standalone tool. Keeping it separate means it can be used independently, works great in pipelines, and doesn’t add complexity to Apex itself. If you want to use it with Apex, you can always pipe it in (the Unix philosophy of doing one thing well).
There are a few good markdown linters available that can be configured to use similar rules — this one is just specific to my own preferences and easy to run. If your preferences happen to align with mine, you might find it useful.
The tool takes STDIN and can be used in a pipeline, and can output to STDOUT or overwrite files. Here’s a quick example:
# Process a file and output to stdout
md-fixup file.md
# Overwrite files in place
md-fixup --overwrite file.md
# Use in a pipeline
find . -name "*.md" | md-fixup --width 100All linters can be enabled or disabled on the command line, via project config files, or via global config (in that order of precedence). So you can customize it to match your exact needs, even if they don’t perfectly align with my defaults.
You can skip specific rules if you don’t want them:
# Skip wrapping and end-of-file newline rules
md-fixup --skip wrap,end-newline file.md
# Or use a config file
md-fixup --init-configThe config file lives at ~/.config/md-fixup/config.yml and lets you set defaults for width, overwrite behavior, and which rules to skip.
There’s a start of a VS Code extension in the repo, but I haven’t fully developed that yet. It’s on the roadmap, but for now the command-line tool works great.
You can install it with Homebrew:
brew tap ttscoff/thelab
brew install md-fixupThe release action is generating macOS and Linux binaries (x86, arm) so you don’t need any external tools to install via Homebrew.
You can also visit the GitHub repo for details on installing the Python version or building the Rust version from source.
Here’s what md-fixup does:
$$ display and $ inline math block spacing (handles multi-line, preserves currency)__, italic: always *)Feedback and code contributions are welcome! If you have opinions about Markdown formatting that differ from mine, I’d love to hear about them. And if you want to help build out the VS Code extension or add new features, pull requests are always appreciated.
See details on GitHub and take it for a spin!
Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on GitHub, Mastodon, and elsewhere.
Sign up for the email newsletter, and keep up with this blog by adding it to your favorite news reader, or following it on Bluesky or Mastodon at @brettterpstra.com@web.brid.gy.