Flowmark is an Atom plugin to auto-format Markdown source.
It draws inspiration from auto-formatting as pioneered by gofmt and previous implementations like markdownfmt, but also does some helpful new things related to wrapping lines for ease of reading and collaboration and cleaning up punctuation.
Flowmark started simply but has become an essential tool for editorial production at Holloway, where we consider powerful but lightweight processes for editing text essential. In addition to formatting, it offers a variety of tools like cleaning up common Markdown problems and “normalizing” footnotes, fixing punctuation, and many other things.
Auto-formatting is known to be a Very Good Thing when multiple programmers work together. But it turns out the same idea can be hard to apply for Markdown, for subtle reasons mostly related to the handling of paragraphs of text.
Existing auto-formatters standardize the common annoyances of inconsistent indentation, different heading styles, and the like.
[^2], etc.) but this is problematic if you ever try to combine multiple Markdown documents into one. For examle if you combine multiple chapters of a book, what if both chapters have a
^1footnote? This option makes that simple and easy if you run it before merging docs.
.:?!) boldface when following boldface text. This is common typographic practice but often done inconsistently.
The real challenge of collaborative editing in Markdown (and I’ve seen this a lot with projects of my own, like TAOCL) is confusing diffs and merge conflicts. These are common and frustrating when multiple people edit paragraph-long lines on large, GitHub-hosted Markdown files.
Flowmark tries a different approach: It intelligently breaks lines at “reasonable” places, usually on sentence boundaries, while still preserving the way the Markdown will render. This may seem like an odd idea at first, but is a solution to two (seemingly conflicting) goals:
The hope is that you—or anyone else you collaborate with—can run it any time to clean up your Markdown consistently and routinely and with minimal diff churn. Other GitHub features also work better: Unlike the situation with paragraph-long lines, shorter lines mean diff line counts and Git blame also become meaningful (just as with a normal programming language). Note that the Flowmark formatting rules are a little complex, but that’s okay, as long as they’re consistent.
Install as usual in Atom, by going to preferences, select install, and search for “flowmark”. You’ll then have a Flowmark menu item under Packages. Or use the hot key Shift-Cmd-M to reformat the whole doc.
The idea of wrapping text based on sentences or phrases from the idea of semantic linefeeds. Auto-formatting Markdown has been done before, notably with tidy-markdown and atom-tidy-markdown (also used in atom-beautify), markdownfmt (in Go), and atom-markdown-format (an Atom plugin based on markdownfmt but now deprecated). These don’t try to reflow text, however. A related approach, just to detect errors, is linter-markdown, which uses remark-lint’s framework in Atom.
Good catch. Let us know what about this package looks wrong to you, and we'll investigate right away.