Skip to content

Add Support for Custom Alert Titles#430

Open
rdestefa wants to merge 1 commit intocommonmark:mainfrom
rdestefa:issue-429-custom-alert-titles
Open

Add Support for Custom Alert Titles#430
rdestefa wants to merge 1 commit intocommonmark: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. The only reason GitHub supports it is because it's originally 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 from 84f6dc9 to a4bc9d1 Compare May 2, 2026 07:35
@rdestefa rdestefa force-pushed the issue-429-custom-alert-titles branch from a4bc9d1 to d649322 Compare May 2, 2026 08:54
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.

1 participant