I’ve picked up the habit of writing all of my notes in Markdown as of late, but I’ve noticed that different text editors seem to format my notes differently. This is fine, but I would like a tool (preferably a command line tool, but an editor plugin is fine too) which can take a file and let me know if it’s properly formatted CommonMark markdown.
I’ve searched for this, but all the results I’ve found have been more like test suites for people writing markdown renderers to ensure that their code can handle the full range of the markdown specification. What I’m looking for is rather the opposite – I want something that interprets the CommonMark spec strictly and then lets me know if what I’m writing passes a stringent interpretation of the specification.
Such a tool cannot exist because every file is a valid Commonmark file. However, there could be a tool that highlights different outputs for the same input, but it would need to ship with or have access to different parsers. Babelmark 2 and 3 are such tools working online. Their purpose is different, not being intended for authors but developers.
You could run Pandoc, for instance, to convert a markdown file into a specific flavor, e.g. --from markdown_strict --to commonmark, and then diff input and output, or you could run it twice with different options and compare the outputs.
Quoting Section 2.1 of the spec:
“Any sequence of characters is a valid CommonMark document.”
So a tool to tell you if you have a valid CommonMark
document would be trivial. Of course, the meaning of
the document might not be what you expect, but to test
for this you’d need a tool that takes as input both
the document and its intended interpretation.
While Markdown validation isn’t really applicable in your use-case, Markdown linting might be useful.
The difference is that a linter isn’t strictly checking whether the markdown is “valid” or “invalid”. Rather, it’s looking for patterns that suggest you made a mistake while writing your markdown. The downside is that it can give you false positives if you’re purposefully writing strange markdown.
For example, at least one Markdown linter includes a rule that flags text like this:
(bad link)[http://www.example.com]
That’s valid Markdown, which renders verbatim: “(bad link)[http://www.example.com]”. But in practice that’s more likely to be an accidental reversal of the [] and () in Markdown link syntax.