search

commonmark / commonmark-java

Java library for parsing and rendering CommonMark (Markdown)
BSD 2-Clause "Simplified" License
2.31k stars 288 forks source link

GFM admonition blocks #327

Open bric3 opened 6 months ago

bric3 commented 6 months ago

Is your feature request related to a problem? Please describe.

Github now support admonition blocks

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

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

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

[!TIP] Optional information to help a user be more successful.

[!IMPORTANT]
Crucial information necessary for users to succeed.

[!WARNING]
Critical content demanding immediate user attention due to potential risks.

[!CAUTION] Negative potential consequences of an action.

Describe the solution you'd like

Ideally adding a new gfm extension to common-mark makes sense, to support this admonition syntax.

Describe alternatives you've considered

No alternative.

Additional context

Source [1], [2]

robinst commented 4 months ago

Hey, thanks for raising this! Yeah, this would be useful. It's interesting that it uses link syntax, and that links take precedence, e.g. in this:

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

[!NOTE]: https://example.org

It's actually a link because of the definition.

I'm currently working on support for footnotes, see https://github.com/commonmark/commonmark-java/issues/273, which needed some more flexibility around link parsing and it has a new API to customize link processing. I think after that is done, admonition parsing should be pretty straightforward.

bric3 commented 4 months ago

I don't know how the internal parsing is working, but the context here seems relevant i.e. when parsing the admonition header, we need to know if it's within a block quote.

harunagic commented 1 month ago

any updates on this?

robinst commented 3 weeks ago

No updates yet. Happy to prioritize this if someone wants to sponsor the work on this.

Some notes from playing around with it:

This is an admonition block, even with the two empty leading lines inside the block quote (not sure how that's done, is there a special check in block quote parsing, or is the marker detected only later in inline parsing, or as a post-processing step?):

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

This is not an admonition block though (trailing spaces after the marker are accepted though):

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