commonmark-ext-gfm-alerts

Extension for commonmark-java that adds support for GitHub Flavored Markdown alerts.

Enables highlighting important information using blockquote syntax with five standard alert types: NOTE, TIP, IMPORTANT, WARNING, and CAUTION.

Usage

Markdown Syntax

> [!NOTE]
> Useful information

> [!WARNING]
> Critical information

Standard GFM Types

var extension = AlertsExtension.create();
var parser = Parser.builder().extensions(List.of(extension)).build();
var renderer = HtmlRenderer.builder().extensions(List.of(extension)).build();

Custom Alert Types

Add custom types beyond the five standard GFM types:

var extension = AlertsExtension.builder()
        .addCustomType("BUG", "Known Bug")
        .build();

Custom types must be UPPERCASE. Standard type titles can also be overridden for localization.

The allowed types (including the five standard GFM types) can also be completely overwritten:

var extension = AlertsExtension.builder()
        .setAllowedTypes(Map.ofEntries(
                Map.entry("IMPORTANT", "Important"),
                Map.entry("WARNING", "Warning")
                Map.entry("BUG", "Known Bug")
        ))
        .build();

Custom Alert Titles

Allow authors to provide custom titles per alert by adding text after the alert marker on the same line:

var extension = AlertsExtension.builder().allowCustomTitles(true).build();

> [!NOTE] Keep in mind <!-- Overrides default title of "Note" -->
> Useful information

> [!WARNING] Be **very** careful <!-- Inline formatting is supported -->
> Critical information

Nesting Alerts

By default, alerts cannot be nested within other blocks. Alerts within other blocks are parsed as regular block quotes.

<!-- Allowed -->
> [!NOTE]
> Useful information

<!-- Not allowed -->
- > [!NOTE]
  > Useful information

This behavior can be changed to allow nested alerts:

var extension = AlertsExtension.builder().allowNestedAlerts(true).build();

Styling

Alerts render as <div> elements with CSS classes:

<div class="markdown-alert markdown-alert-note" data-alert-type="note">
  <p class="markdown-alert-title">Note</p>
  <p>Content</p>
</div>

Basic CSS example:

.markdown-alert {
  padding: 0.5rem 1rem;
  margin-bottom: 1rem;
  border-left: 4px solid;
}

.markdown-alert-note { border-color: #0969da; background-color: #ddf4ff; }
.markdown-alert-tip { border-color: #1a7f37; background-color: #dcffe4; }
.markdown-alert-important { border-color: #8250df; background-color: #f6f0ff; }
.markdown-alert-warning { border-color: #9a6700; background-color: #fff8c5; }
.markdown-alert-caution { border-color: #cf222e; background-color: #ffebe9; }

Icons can be added using GitHub's Octicons:

License

See the main commonmark-java project for license information.