Small aside: Microsoft GitHub’s proprietary Markdown fork is certainly not 90% compatible—most egregious IMO was overloading blockquote semantics with callouts which breaks semantics all over the web. Some providers & forks have had to support their fork due to the monopoly control MS GitHub asserts.
Ye fair, it all depends on what markup you have and what features you use. Personally i dont think my markup of priiloader has any weird stuff that is specific to github, but i will have to check to be honest. If there was any special stuff id try to steer away from github specifics as much as i can, because i believe and work in a way it should always be possible to take away any part of a project and replace it with something else. It makes projects very flexible to change
The real issue is the base Markdown spec is absolutely barren. Folks have tried to shoehorn Markdown into something general purpose so everyone & their brother needed to fork it to add some level of usability since base Markdown isn’t suitable for blogging, technical documentation, white papers, etc. which it was never designed to do
Do you mean admonitions? E.g. info, warning, etc? There’s precedent for that in commonly-used open source implementations, e.g. obsidian.md (which uses the same syntax, and started before). What semantics does it break? It’s designed to read well in plaintext and render nicely even if used in a renderer that doesn’t support admonitions, e.g.
[!NOTE]
Information the user should notice even if skimming.
As opposed to other common markdownish implementations that use nonsensical plaintext which renders poorly in alternative renderers. Here’s a discussion on the topic in the CommonMark forums.
Read the Markdown spec where it says the > denotes a blockquote. There isn’t room to overload it without breaking that into something not backwards compatible (such as CommonmsMark which will follow the spec & render a blockquote—which, according to the HTML spec, must be text quoting a source). Just because some of the bigger players—namely the proprietary forks, Obsidian & MS GitHub—doesn’t mean it’s not breaking with the original spec. Go ahead & do it, but don’t lie & say it is Markdown or Markdown-compatible. Instead these entities try to push & sway everyone to adopt their syntax rather than working with say CommonMark with RFCs.
CommonMark has the ::: block syntax, but folks using this are relying on stringly-typed, not-well-defined options when they do ::: note as it just becomes a CSS class where anyone could style it.
As callouts are such an everpresent construct in technical writing, documentation, & so on, what you need is first-class support. Docbook as an output has first-class support, but sadly W3 shot down the last attempt at an element proposal (but can be properly by manually constructed with role=note & aria-labelledby). reStructuredText & AsciiDoc are both lightweight markup syntaxes that support first-class callouts & other elements (definition lists, summary/details, figures, etc.) as well as having first-class metadata (like basically every other creative work format for images, audio, documents).
All of this is to say what Microsoft is doing is no longer Markdown & only they hold the keys to the spec (you can complain in their forums, but you can’t submit an RFC or pull request). But also, Markdown / CommonMark are honestly ill-suited for the task of technical writing since it doesn’t support basic features for that task (embedding HTML defeats the purpose & portability)—and instead we have a lot of ad-hoc hacks & bad HTML output due to choosing the wrong tool for the job.
Small aside: Microsoft GitHub’s proprietary Markdown fork is certainly not 90% compatible—most egregious IMO was overloading blockquote semantics with callouts which breaks semantics all over the web. Some providers & forks have had to support their fork due to the monopoly control MS GitHub asserts.
Ye fair, it all depends on what markup you have and what features you use. Personally i dont think my markup of priiloader has any weird stuff that is specific to github, but i will have to check to be honest. If there was any special stuff id try to steer away from github specifics as much as i can, because i believe and work in a way it should always be possible to take away any part of a project and replace it with something else. It makes projects very flexible to change
The real issue is the base Markdown spec is absolutely barren. Folks have tried to shoehorn Markdown into something general purpose so everyone & their brother needed to fork it to add some level of usability since base Markdown isn’t suitable for blogging, technical documentation, white papers, etc. which it was never designed to do
Do you mean admonitions? E.g. info, warning, etc? There’s precedent for that in commonly-used open source implementations, e.g. obsidian.md (which uses the same syntax, and started before). What semantics does it break? It’s designed to read well in plaintext and render nicely even if used in a renderer that doesn’t support admonitions, e.g.
As opposed to other common markdownish implementations that use nonsensical plaintext which renders poorly in alternative renderers. Here’s a discussion on the topic in the CommonMark forums.
Read the Markdown spec where it says the
>denotes a blockquote. There isn’t room to overload it without breaking that into something not backwards compatible (such as CommonmsMark which will follow the spec & render a blockquote—which, according to the HTML spec, must be text quoting a source). Just because some of the bigger players—namely the proprietary forks, Obsidian & MS GitHub—doesn’t mean it’s not breaking with the original spec. Go ahead & do it, but don’t lie & say it is Markdown or Markdown-compatible. Instead these entities try to push & sway everyone to adopt their syntax rather than working with say CommonMark with RFCs.CommonMark has the
:::block syntax, but folks using this are relying on stringly-typed, not-well-defined options when they do::: noteas it just becomes a CSS class where anyone could style it.As callouts are such an everpresent construct in technical writing, documentation, & so on, what you need is first-class support. Docbook as an output has first-class support, but sadly W3 shot down the last attempt at an element proposal (but can be properly by manually constructed with
role=note&aria-labelledby). reStructuredText & AsciiDoc are both lightweight markup syntaxes that support first-class callouts & other elements (definition lists, summary/details, figures, etc.) as well as having first-class metadata (like basically every other creative work format for images, audio, documents).All of this is to say what Microsoft is doing is no longer Markdown & only they hold the keys to the spec (you can complain in their forums, but you can’t submit an RFC or pull request). But also, Markdown / CommonMark are honestly ill-suited for the task of technical writing since it doesn’t support basic features for that task (embedding HTML defeats the purpose & portability)—and instead we have a lot of ad-hoc hacks & bad HTML output due to choosing the wrong tool for the job.