Description
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.