You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The text was updated successfully, but these errors were encountered:
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:
Where KEYWORD could be NOTE, TIP, WARNING, IMPORTANT, CAUTION, etc.
HTML Output: Transform these recognized blocks into specific, semantic HTML elements. For example:
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
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.
The text was updated successfully, but these errors were encountered: