search

Python-Markdown / markdown

A Python implementation of John Gruber’s Markdown with Extension support.
https://python-markdown.github.io/
BSD 3-Clause "New" or "Revised" License
3.71k stars 856 forks source link

Add support for GitHub Flavored Markdown new admonitions ("alerts") #1423

Closed llucax closed 8 months ago

llucax commented 8 months ago

GitHub just added support for alerts which are very very similar to admonitions.

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

It would be great if the admonitions extension supports also the GitHub syntax, so one can write admonitions in a style that will also be parsed specially by GitHub and show properly.

facelessuser commented 8 months ago

This should already exist via https://github.com/oprypin/markdown-callouts. Did GitHub change its syntax from what is offered there? If so, you should maybe create an issue there.

llucax commented 8 months ago

I don't see any mentions there saying that the syntax is supposed to be supported by GitHub, it seems just like an alternative syntax to admonitions, so I'm not sure if that's really the right place for this issue. Maybe it is worth its own extension or something, not sure, but just saying that I don't think GitHub ever supported any other syntax for admonition-like blocks.

facelessuser commented 8 months ago

It was supposed to. The syntax they use used to work in GitHub. That's why he created it so that they'd render in GitHub, which the default admonitions did not.

> NOTE: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
> nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
> massa, nec semper lorem quam in massa.

Then GitHub recently did a pivot and now uses this new format which is used by Microsoft: https://learn.microsoft.com/en-us/contribute/content/markdown-reference#alerts-note-tip-important-caution-warning.

See relevant issue: https://github.com/oprypin/markdown-callouts/issues/13

Regardless, Python Markdown has been generally resistant to adding new plugins and encourages people to use the extension API to create 3rd party extensions to keep the maintenance burden low on this project. This project already offers admonitions and has been there for years and is unlikely to change its syntax breaking users reliant on this format.

llucax commented 8 months ago

OK, it is probably not relevant anymore, but still I don't see anywhere that GitHub ever supported the syntax in markdown-callouts, that repo only says it uses a different syntax for graceful degradation, it doesn't say it was ever rendered specially by GitHub.

llucax commented 8 months ago

OK, closing because from what I read here it seems it makes more sense to implement it as a separate extension (this extension being markdown-callouts or not).