Skip to content

Feature Request: Native Support for GitHub-Style Alert/Callout Syntax (e.g., > [!NOTE]) #2724

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Leroy-X opened this issue Jun 4, 2025 · 0 comments
Labels
C-enhancement Category: Enhancement or feature request

Comments

@Leroy-X
Copy link

Leroy-X commented Jun 4, 2025

Problem

Mdbook currently lacks native support for the GitHub-style alert/callout syntax (e.g., > [!NOTE]). Authors wishing to use this intuitive and widely adopted syntax must find, install, and configure third-party preprocessors. This adds an extra layer of setup and dependency management for a very common and useful formatting feature.

Proposed Solution

Integrate native parsing for GitHub-style alerts directly into Mdbook.
Recognition: Mdbook's Markdown parser should recognize blockquotes formatted as:

> [!KEYWORD]
> Content of the alert.
> More content.

Where KEYWORD could be NOTE, TIP, WARNING, IMPORTANT, CAUTION, etc.
HTML Output: Transform these recognized blocks into specific, semantic HTML elements. For example:

<div class="mdbook-alert mdbook-alert-keyword" data-alert-type="KEYWORD">
  <p class="mdbook-alert-title">KEYWORD (or Optional Title)</p>
  <div class="mdbook-alert-content">
    <p>Content of the alert.</p>
    <p>More content.</p>
  </div>
</div>

The class names (mdbook-alert, mdbook-alert-keyword, mdbook-alert-title, mdbook-alert-content) should be standardized to allow easy CSS styling.
Styling: Provide minimal default styling or github alert styling, relying on users to style these alerts via their theme/custom.css. The key is providing the correct HTML structure.

Notes

  • Simplicity & Reduced Friction: Native support eliminates the need for users to manage external preprocessors for this common feature, simplifying setup and lowering the barrier to entry.
  • Consistency & Standardization: Provides a standard HTML output, leading to more consistent rendering and easier theming across Mdbook projects.
  • Improved Authoring Experience: Aligns Mdbook with a popular and intuitive Markdown extension used in many other platforms (GitHub, Typora, Obsidian), making it more familiar for authors.
  • Discoverability & Core Functionality: A feature as common as alerts feels like it should be a core part of a documentation generator, readily available without extra steps.
  • Reduced Build Complexity: Slightly streamlines the build process by internalizing this common transformation.

While third-party preprocessors are valuable for extensibility, the ubiquity and utility of GitHub-style alerts make a strong case for their inclusion as a built-in Mdbook feature.
Thank you for considering this.

@Leroy-X Leroy-X added the C-enhancement Category: Enhancement or feature request label Jun 4, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-enhancement Category: Enhancement or feature request
Projects
None yet
Development

No branches or pull requests

1 participant