Formal specification for extensions beyond "standard" Markdown

[srawlins]

This markdown package currently supports one non-standard syntax (the code fence), and there are open issues requesting support for more (see #1466, dart-lang/markdown#38, dart-lang/markdown#41, and dart-archive/markdown#31). It's of course up to the maintainers whether to include any more non-standard syntaxes beyond code fences, but the none of these issues has been outright rejected.

When syntax extensions are supported in a Markdown parser, they should be able to be toggled, to reduce surprises (see Pandoc, Redcarpet, and others). This is the primary reason for having a formal specification: this package shouldn't format a user's Markdown strangely because it chose to include one certain non-standard syntax, and to always include it.

I propose a new argument to markdownToHtml() and new Document(), perhaps List<String> extensions. This argument defaults to []. The different values might include:

• "code_fences" (already implemented)
• "inline_html" (Minor change to kick off mirroring #18)
• "tables" (Error handling for malformed session file #38)
• "no_intra_word_emphasis" (Update README.md #41)
• "header_ids" (Adding more information to LogFileStats + minor updates to tests #31)

I realize that this package already supports user-written, inline syntax extensions per-document, but supporting user-written block syntaxes would be very hard, as they would want access to the different private patterns, etc (for example how ListSyntax uses all the other block syntax patterns to see whats up). So if this opens the door to non-standard block syntaxes like tables, and definition lists, then its a super win.

This new argument also eases some anxiety of adding a new syntax extension: it will always be safely disabled by default, and only enabled when the user chooses to use it.

If y'all like the idea, I'm happy to send a PR adding the argument, and disabling the FencedCodeBlockSyntax by default.

[munificent]

Yeah, this is a good idea. There are other structural changes I'd like to do in the package, but my time to work on it is really limited right now. How about we leave this bug open for now and if I get some time to modernize the package overall, we'll do it then?

[srawlins]

Hey @munificent ,

I just sent a PR for this formalization. If you have concrete ideas for the structural changes you want to make, could you open an issue? I might have time for it.

In any case, can we accept the formalization before the restructuring?