Add an extension to support GitHub alerts

[njzjz]

Describe the feature you'd like to request

Last week, GitHub supported alerts as follows:

> [!NOTE]
> This is a note

Note

This is a note

See:

• https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/
• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

I hope myst-parser can add an extension to provide the same feature to provide a consistent preview for GitHub and Sphinx.

Describe the solution you'd like

Add an option to myst_enable_extensions to allow such syntax.

Describe alternatives you've considered

No response

[chrisjsewell]

Heya, it would probably be best if one first implemented a plugin in https://github.com/executablebooks/mdit-py-plugins

My only word of warning here, is that

1. They have already flip-flopped on this, changing from the initial syntax they had before November 2023 > **Note** to this new one, lets hope they don't change again 😒
2. I would agree with others in the comments for this feature; https://github.com/orgs/community/discussions/16925#discussioncomment-2794978, it basically tends to break the semantics of the blockquote syntax

Its also frustrating that Github seem to have abandoned their past spec for Github Flavoured Markdown, https://github.github.com/gfm/, when implementing these new features.

[orsinium]

+1 to the feature. While the syntax introduced by Github may suck, it is quite convenient to be able to produce documentation that is rendered in about the same way in both Github and Myst-powered web pages. Currently, the admonitions look bad on Github:

[henryiii]

They only flip-flopped on it while developing it, and it seems to be quite stable now and documented in their help pages.

[KyleKing]

I have a parser and render implemented in mdformat-gfm-alerts (https://github.com/KyleKing/mdformat-gfm-alerts?tab=readme-ov-file#mdformat-gfm-alerts), which is built on my generic admonition package. The only caveat for now is that I haven't figured out how to remove the outer block quote yet

Update: HTML rendering is now correct

[ihrke]

@KyleKing this is interesting, how can I use mdformat-qfm-alerts together with myst-parser?

[timkpaine]

This has been working well for me: https://github.com/python-project-templates/yardang/blob/b87fed488ac95ac99997d53fcb6cf1807b5f4ab4/yardang/conf.py.j2#L156

[KyleKing]

You should be able to add ‘mdformat-gfm-alerts’ like any other plugin (e.g. with pip install, poetry add, uv add, etc.) and it will be discovered automatically by mdformat and shouldn’t interfere with mdformat-myst

Doing a find and replace of GFM Admonitions is also a valid approach!

[KyleKing]

Actually, a correction, for Sphinx and when rendering in general, I would probably recommend @timkpaine's approach because while mdformat-gfm-alerts has minimal rendering, it doesn't properly handle replacing the blockquotes. For mdformat-myst integration to format the raw markdown, I would recommend mdformat-gfm-alerts as described above

[ihrke]

Thanks for the advice! I have some trouble implementing @timkpaine 's advice. In my case, I use ..include ../README.md with the myst-parser from index.rst to include the Github MD-file. However, it seems that the sphinx source-read event is not triggered with the contents of this file (it is only triggered by index.rst with the contents of that file). Any ideas how to fix this?

[s-weigand]

@ihrke I had the same issue with include. The solution is to connect to the include-read event instead of the source-read event.
Note that that you also need to adjust the function signature since the include-read expects a different callback

- def run_convert_github_admonitions_to_rst(app, filename, lines):
+ def run_convert_github_admonitions_to_rst(app, relative_path, parent_docname, lines):

Just for completeness there is a nice flow diagram explaining the event flow.