MarkFlow: Make Your Markdown Sparkle!

00. Beautifully Formatting Your Markdown

About a year ago, one of my coworkers introduced me to black, a python tool that takes python source code and spits out a consistent file following a set of rules. Coming from code bases where such choices were made on a whim and could change within a file, I was sold. When I realized I could write the laziest looking Python code I wanted and it would take care of it for me, I knew I had found true love.

Having recently gotten addicted to Markdown, I scoured the internet for a Markdown reformatter. My excellent Google-fu found prettier while my terrible reading comprehension did not notice that it did things other than code. So, I set on down the road to write my own Markdown formatter, and today it is released for everyone to use.

The tool is called MarkFlow and it works like so:

fred@the-protector ~/> markflow this_looks_terrible.md
reformatted this_looks_terrible.md
All done!
1 file was reformatted.

...and bam, this_looks_terrible.md doesn’t look so terrible anymore. What does MarkFlow do? Great question there, imaginary reader. It:

• Reflows all of your paragraphs to a certain length (88 by default)
• Fixes your underlined headings so they’re correctly underlined
• Ensures your ordered lists are numbered properly
• Removes extraneous line ending whitespace
• Aligns table borders to give them that table feel even if you don’t want to put in the effort
• Make unordered lists use consistent markers
• Indents list entries so they look nice

...and more … I have a terrible memory

It also comes with a --check to make sure these rules are being followed. And it will not reformat a file if the output would end up being reformatted into some different representation. From my very biased point of view and having used this tool for months, just the paragraph reflowing has made editing Markdown files so much easier.

If any of this interests you, checkout the README in the project for more examples of what changes it makes. (Or don’t. Clearly I couldn’t be bothered to do so when writing this post.) You can also install it and start playing with it right away (Note: it does require Python 3.6 or greater):

> pip install markflow
...
Successfully installed colorama-0.4.3 commonmark-0.9.1 markflow-0.1.0 pprintpp-0.4.0 pygments-2.6.1 rich-1.3.1 typing-extensions-3.7.4.2
> markflow twilight_fan_fic_chapter_139.md

If you’re interested in more, check out the source on GitHub. Contributions are certainly welcome!

P.S. As an alternative to just using pip, checkout pipx to make tools like MarkFlow available globally but installed and running in their own environments.