search

KyleKing / mdformat-admon

mdformat plugin for admonitions
MIT License
8 stars 2 forks source link

Support New GitHub Admonition Format #19

Closed blink1073 closed 6 months ago

blink1073 commented 6 months ago

GitHub has changed its admonition format, https://github.com/orgs/community/discussions/16925.

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

Renders as

[!NOTE]
Highlights information that users should take into account, even when skimming.

However, currently, it gets escaped by mdformat, even with this plugin installed.

> \[!NOTE\]  
> Highlights information that users should take into account, even when skimming.
KyleKing commented 6 months ago

Thanks for letting me know! I'll add official support when I have a chance

In the interim, you could try adding 'mdformat-wikilinks', which may prevent the brackets from being escaped

(Note to self: should probably introduce an auto-fix from the old to new style admonitions & to ensure that there isn't an extra newline)

blink1073 commented 6 months ago

Thanks! Unfortunately that plugin did not prevent the escaping.

KyleKing commented 6 months ago

I'm starting a package to identify and format those alerts this weekend now that I'm back from a trip! (https://github.com/KyleKing/mdformat-gfm-alerts/issues/1)

On a side-note, I've been following the community discussion, but I haven't come across a response from the GitHub staff on why they haven't adopted an existing syntax (my guess is that the blockquotes appears to work better with npm/pypi/etc. rendering, but that has the same accessibility concerns?). I'm not sure if you have? I don't love having yet another standard, which makes more work for the OSS community (e.g. https://github.com/incentro-dc/remark-github-admonitions-to-directives) 😢

Update: looks like the syntax is from a MicroSoft internal format, which means that the discussion announcement is just perfunctory (https://github.com/orgs/community/discussions/16925#discussioncomment-8729846)

blink1073 commented 6 months ago

I agree with your sentiments, and no I have not seen any other communication or reasoning other than the post I linked. Thank you for taking on this feature!

KyleKing commented 6 months ago

Released 🎉 https://pypi.org/project/mdformat_gfm_alerts

Let me know if you find any issues or have follow up questions

blink1073 commented 6 months ago

Works as advertised, thanks very much!

jan-kouba commented 2 months ago

Hi, will the mdformat-gfm-alerts package be included into the mdformat-gfm package eventually?

KyleKing commented 2 months ago

Hi @jan-kouba, the problem is philosophical that mdformat-gfm implements the spec from Github Flavored Markdown (cmark-gfm and see), while the Alerts are only documented on Github's website.

I'm not sure what the future will hold. I've considered renaming mdformat-gfm-alerts into mdformat-github to philosophically align with the Github online docs, but there isn't enough technical clarity to build a formatter/renderer

jan-kouba commented 2 months ago

Hi @jan-kouba, the problem is philosophical that mdformat-gfm implements the spec from Github Flavored Markdown (cmark-gfm and see), while the Alerts are only documented on Github's website.

I'm not sure what the future will hold. I've considered renaming mdformat-gfm-alerts into mdformat-github to philosophically align with the Github online docs, but there isn't enough technical clarity to build a formatter/renderer

Ok, clear, thanks!