Skip to content

Add Support for Custom Alert Titles#430

Open
rdestefa wants to merge 6 commits into
commonmark:mainfrom
rdestefa:issue-429-custom-alert-titles
Open

Add Support for Custom Alert Titles#430
rdestefa wants to merge 6 commits into
commonmark:mainfrom
rdestefa:issue-429-custom-alert-titles

Conversation

@rdestefa
Copy link
Copy Markdown
Contributor

@rdestefa rdestefa commented Apr 29, 2026

Made an initial attempt at implementing support for custom titles in alerts (#429). I kept running into issues when trying to enhance the post processor because there's no access to an inline parser and it was susceptible to edge cases where inline nodes would overlap between the title and the body. For example:

> [!TIP] 2*2 = 4
> But 3*3 = 9

The *s would create an Emphasis node which made splitting out the title text difficult, when in reality those lines should be parsed separately. I decided to try and make a custom AlertBlockParser instead to have more control.

I'm not sure if this is the right approach, but it seemed to work well for me. A few things I noticed, though, with this new parser:

  • Alert markers take precedence over link reference definitions. This is opposite of what GitHub does, but in line with what GitLab does. My guess is that this isn't intentional by GitHub, and just a side effect of how they post-process after initial parsing has completed. To me this seems like an extremely rare edge case, and it's more likely the author wanted an alert than a link if they put a marker in that specific spot.
  • Currently lazy continuation is not allowed between the title and the body text, for example:
    > [!NOTE] Title
    Lazy body
    GitHub allows this, but GitLab doesn't. To me the latter seems correct because they are technically two separate nodes. This also seems to be in line with this part of the CommonMark spec. GitHub's support for this also seems unintentional and just a side-effect of it originally being parsed as BlockQuote > Paragraph, and the paragraph allows lazy continuation.
  • This new parser has a configuration to allow alerts to be nested within other blocks (even other alerts). GitHub doesn't allow this, but GitLab does. I could also separate this out into a different PR.
  • Should alerts without a body be allowed? For example:
    > [!NOTE]
    
    > [!NOTE] Title
    Currently it's not allowed. GitHub disallows this, but GitLab allows it.

@rdestefa rdestefa force-pushed the issue-429-custom-alert-titles branch 2 times, most recently from 3ba29d4 to 84f6dc9 Compare May 2, 2026 07:23
@rdestefa rdestefa changed the title Allow Custom Alert Titles Add Support for Custom Alert Titles May 2, 2026
@rdestefa rdestefa force-pushed the issue-429-custom-alert-titles branch 4 times, most recently from d26df85 to 979a0d1 Compare May 3, 2026 11:05
@rdestefa
Copy link
Copy Markdown
Contributor Author

@robinst If you have a chance would you be able to take a look at this PR? Thanks!

Copy link
Copy Markdown
Collaborator

@robinst robinst left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work so far (and thanks for your patience)! Requested some changes, mainly around edge cases and preserving source position information.

* These comments will be visible when rendered to other formats like
* Markdown, so this is only relevant for the HTML renderer.
*/
if (isCommentOnlyTitle(first)) {
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does GitLab do this? Seems like a strange edge case to support.

Copy link
Copy Markdown
Contributor Author

@rdestefa rdestefa Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GitLab doesn't do this because they treat the entire title content as raw text instead of parsing inlines (example). It seems like supporting inlines makes sense, however, so I did that. When I was playing around with it I noticed this edge case where the title would render but appear empty since it's just an HTML comment. I could see someone writing something like:

> [!WARNING] <!-- Remove once this feature is GA -->
> This feature is experimental. Use at your own risk. 

If you don't think it's worth supporting though happy to remove.

@commonmark commonmark deleted a comment from boyshell May 30, 2026
@rdestefa rdestefa force-pushed the issue-429-custom-alert-titles branch 3 times, most recently from 253f5d7 to bf5d808 Compare June 1, 2026 09:45
@rdestefa rdestefa force-pushed the issue-429-custom-alert-titles branch from bf5d808 to f27483f Compare June 1, 2026 09:59
@rdestefa rdestefa requested a review from robinst June 1, 2026 10:31
@rdestefa rdestefa force-pushed the issue-429-custom-alert-titles branch from 5ba66ba to c910716 Compare June 1, 2026 10:45
@rdestefa rdestefa force-pushed the issue-429-custom-alert-titles branch from c910716 to 348d18b Compare June 1, 2026 10:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants