Standardize listing of Markdown Flavors used in the MD document: GLFM, GFM, QMD, etc

1

Standardizing a single common Markdown syntax seems like an impossible challenge!

So, now we already have a lot of different popular “flavors” for Markdown syntax: CommonMark, GitLab Flavored Markdown (GLFM), GitHub Flavored Markdown (GFM), Quarto (QMD), Markdown Extra, MultiMarkdown, R Markdown, etc.

And have a lot of .md files that can use different flavors, even more than one in a single document…

But we have no standardized approach to describe which flavors should be used to render this specific .md file!

As a result, file viewers can only guess which flavor to try to apply to render the document correctly!

Let’s fix this by proposing a standard to list the flavors, used in the current document, to give the viewers and renderers a clue how to render this Markdown file correctly.

My proposal is to recommend using the Front Matter block with the flavors key like this:

---
title: Foo
flavors:
  - GFM
  - R-Markdown
---
The markdown body.

The list of flavor names is already tracked in the RFC RFC 7764 - Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations , as I understand, so we can use the naming vocabulary from there, and the RFC contains links to the references.

Also, we can name this key not as flavors but as extensions or plugins to be clearer.

The list of flavors is an array, to make it possible to set the priorities (first is the winner) of how to render specific blocks, if they are covered by more than one flavor.

Alternatively, we can put a link to the specifications in addition to the flavor name (unique id) in this list, but in such a case, we should standardise the format of the specification, that is a hard challenge too.

What do you think about this idea?

1 Like
2

Cross-posted to the GitHub issue: Proposal: Standardize listing of Markdown Flavors used in the MD document: GLFM, GFM, QMD, etc · Issue #830 · commonmark/commonmark-spec · GitHub

3

Since you know about RFC 7764, you probably already noticed yourself that RFC 7763 introduces a variant parameter for protocols and formats that support ones, e.g. HTTP or MIME email. For some reason, most file systems do not support something compatible, though.

I don’t see why you would need a different name for your proposed use within YAML headers. However, the very existence of such headers constitutes an extension to Commonmark or Markdown and therefore cannot occur in every variant.
In conclusion, it would be the wrong place in the stack of presentation layers to store that meta information in.

1 Like
4

The RFC 7763 describes a single variant for a document, and I don’t see in the RFC any recommendation on how to define this variant in the .md file. Actually, I am okay to use the term “variant” instead of “flavor”.

But as I see in reality, we can have a mix of variants in a single document, therefore people call them “flavors”, not “variants”, because one file can use multiple flavors.

This is the reason why I recommend allowing the definition of a list of variants, not only a single variant. Maybe this is not a good idea, but we have what we have :wink:

So, let’s maybe just rename “flavors” to “variants” and keep the array?

5

How would you use multiple flavors or variants within a single document? Several renderers may produce the same output, if configured accordingly, but the author writes the document in accordance to a single specification.

Many renderers allow to turn on or off options, extensions, modules, features or something like that (e.g. “pipe tables” or “double-tilde strike-through”). A certain collection of those makes a flavor or variant (together with a base like Commonmark).