vfmd

Vanilla Flavored Markdown (vfmd) Parser in Go

vfmd (Vanilla Flavored Markdown) is a sane Markdown variant with an unambiguous specification of syntax. This package is a pure-Go implementation of a parser for vfmd, with additional design goals and some more specific characteristics listed below:

Goals

• Adhere to the vfmd spec (fixing it as needed);
  • Done, with a notable exception of inline HTML;
  • Any assumed issues found in process reported as a pull request;
• Allow for any custom renderers, by outputting an intermediate format ("AST");
  • Done, a flattened tree representation is generated;
  • As an example and proof of concept, a HTML renderer is provided;
• Provide end-to-end mapping from input characters to the final parsed form (this can make it useful e.g. for syntax-highlighting);
  • Partially done: fulfilled for blocks, still TODO for spans (I tried to prepare for that, but it may well need API changes, so possibly this may require creating a new version, i.e. vfmd.v2 or later);
• Allow quick top-level-only parsing (e.g. to scan headers in order to build a Table of Contents);
  • Done;
• Pure Go;
  • Done;
• Try to determine worst-case efficiency (and then maybe try to reduce it);
  • TODO;
  • (Note: I think it should be possible to have it at least as good as amortized O(nmk²), where n is number of lines, m is deepest nesting level of blocks, and k is length of the longest paragraph (more strictly, text span sequence). But I absolutely haven't confirmed yet if the current code has such efficiency characteristics.)

More detailed characteristics

• Extensible syntax (thanks to the vfmd spec) ― both for block- and span-level markup;
  • As an example, subpackage x/mdgithub provides some extensions from GitHub-flavored Markdown: strikethrough with ~~ and fenced code blocks with triple backtick. The cmd/vfmd sample application shows how to enable those (when executed with --github flag).
  • TODO: add tables support from GH-flavored MD too.
• Quite well-tested (thanks to the vfmd testsuite);
• Does not support inline HTML (at least currently; this is arguably a feature for some use cases, like desktop editors or comment systems);
• Does not support inline HTML entities (like & etc.) ― Unicode should make up for that;
• TODO: the QuickHTML renderer does not currently filter URLs in links to protect against e.g. JavaScript "bookmarklet" attacks;
• FIXME: detect md.HardBreak tag for lines ending with " \n";
• FIXME: godoc
• FIXME: example in README
• FIXME: add tests for GitHub-flavored Markdown extensions;
• FIXME: true Region information in spans (vfmd.v2?)
• TODO: make DefaultDetectors comparable?
• TODO: add SmartyPants extensions (also, <a name="..." /> anchors if not there);
• TODO: add tests from Blackfriday too;