GFM like admonitions/callouts

[antonk52]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Motivation

Github is experimenting with adding admonition/callout support to GFM. When and if the solution stabilises it would be nice to make docusaurus compatible with this solution as this would make it easier to reuse markdown content that was initially written for github. Another point for it is to lower the learning curve as GFM is an industry standard.

From this comment I can see that there are known issues with current admonition implementation and there are plans to fork it #6246.

Two examples of this feature:

Note At time of creation GFM callouts is an experimental feature and is discussed here

Warning GFM callouts currently only support Note| Warning variations while docusaurus docs mention support for note | tip | info | caution | danger

Self-service

• [ ] I'd be willing to do some initial work on this proposal myself.

[Josh-Cena]

I've discussed about this with @erickzhao on Discord, and I've also left a comment here: https://github.com/facebook/docusaurus/pull/7152#issuecomment-1133818431 (BTW, you mentioned https://github.com/facebook/docusaurus/issues/6246, which will be realized in this PR)

I do think it would be cool if we can support this OOTB. @wooorm are there plans to support this with remark-gfm?

This also has important implications about how we should treat GitHub Markdown. A lot of these stuff (like this feature) can be implemented in user-land with a very trivial Remark plugin. Do we necessarily need to maintain 100% feature parity? I'm tempted to say "yes", but I'm not sure what others think.

There are other cool new features like the new themed image which will replace the old syntax, the latter of which is documented by us as "implementable in user-land".

[wooorm]

There is a ton of feedback for GitHub to do something else: https://github.com/github/feedback/discussions/16925

Also, feature parity, if possible, would be super buggy: GH has been introducing a bunch of broken things recently, e.g: https://nschloe.github.io/2022/05/20/math-on-github.html

[Josh-Cena]

Ugh, right.

Let's say the syntax gets eventually finalized and specced (?)—doesn't matter if it resembles the current one at all. I'm curious that, if remark-gfm is going to support it, would it be like our implementation with a type: "admonitionHTML" node, or to hardcoded markup (like it has been for footnotes, IIRC)?

Also worth noting that MDN docs use quite the same syntax. So there should be a non-trivial number of people already using it in the wild.

With that said, I agree with some of the sentiments in the thread that overloading the semantics of blockquotes is not a good idea. I'll also be leaning towards using HTML tags.

[wooorm]

The new notes, similar to math and mentions, but unlike footnotes and say tables, are done on the HTML tree. So they are not part of GFM itself, which is an extension to a parser, but instead something done on the tree.

I haven’t really look at what regex they look for, but I believe https://github.com/syntax-tree/hast-util-find-and-replace could do the things they do!

I believe the MDN docs do use micromark/remark/rehype as well, and its open source, so we might be able to find their source code.

[Josh-Cena]

Ah, I get it—makes sense. Yes, MDN does work on the HAST, see https://github.com/mdn/yari/blob/9fdc643900719ea54ad415119998d73d0784cb6b/markdown/m2h/handlers/index.js#L80-L99 (And their contributing guidelines also mentioned that you can use HTML to get the same effect—I can't find it right now)

[slorber]

Between maths, themed images, admonitions, Mermaid... they are clearly giving us some additional work 🤪

Let's wait a bit and see how this turns out

[ken-okabe]

I think that beta implementation by the GitHub guy is really careless, and I commented there

https://github.com/orgs/community/discussions/16925#discussioncomment-3526290

That was a bad syntax.

[toastal]

Also worth mentioning is that it’s a proprietary specification. The best you can do as a user is leave a comment on a discussion board if you’re unhappy & would like to see or propose a change. They have already changed the implementation since this, but there isn’t like a commit or discussion users can see about how/why it was done.

[LuudJanssen]

For anyone interested; I created a Remark plugin to transform GitHub's syntax to the directives syntax used by admonitions: remark-github-admonitions-to-directives

[silverwind]

Likely a good idea to incorporate that plugin into docusaurus for GFM rendering compatibility.