aDOMonitions

Styled admonition callouts generated on page load, for static site generators whose Markdown renderer doesn't support them.

Check out the Quickstart to get up and running right away!

Look at the Demo page to view all the callouts and themes:

Wait, but what is it?

Admonitions are highlighted callout boxes ("Note", "Warning", "Tip", etc.) used to draw attention to important content. Normally Markdown renderers only support these via build-time plugins, so without them the markers end up as plain text in the HTML.

aDOMonitions is a JavaScript library that scans the DOM for admonition markers in HTML generated by a static site generator without admonition support. It then transforms the corresponding HTML into styled, accessible callout boxes with icons, colours, and ARIA roles.

For example, a GitHub style Markdown Admonition:

> [!WARNING]
> This will delete all data.

Is likely converted to this raw HTML by static site generators without built-in admonition support:

<blockquote>
  <p>[!WARNING]</p>
  <p>This will delete all data.</p>
</blockquote>

Running aDOMonitions transforms that HTML into this styled callout box, with accompanying CSS for colours, layout, and an icon:

<div class="adomonitions adomonitions-warning" role="alert" aria-label="Warning">
  <p class="adomonitions-title">
    <span class="adomonitions-icon" aria-hidden="true"><!-- SVG --></span> Warning
  </p>
  <p>This will delete all data.</p>
</div>

Install and run

npm install adomonitions

import { init } from "adomonitions";
init(); 

Or load via a <script> tag (UMD):

<script src="https://unpkg.com/adomonitions/dist/adomonitions.umd.min.js"></script>
<script>
  adomonitions.init();
</script>

Check out the Quick Start guide for more examples.

Themes

Eight bundled themes. The active theme is injected automatically as a <style> tag:

Theme	Description
default-light default-dark default-auto	Tinted background with rounded corners, default
github-light github-dark github-auto	GitHub callout style (transparent bg, left border highlight), light
material	MkDocs Material style (full border, colour in title background, smaller text size)
docusaurus	Docusaurus/Infima style (thick border, heavier title)

Set theme: null to skip CSS injection and bring your own styles. Standalone CSS files are also available at dist/themes/ for use via <link> tags.

Documentation

• Quick start: Install and init, full HTML example
• Configuration reference: All options with defaults and examples
• Customisation guide: CSS overrides, custom icons, BYO themes, dark mode

License & Acknowledgements

MIT licensed.

Icons are inline SVGs from GitHub Octicons, MIT licensed (see LICENSE-THIRD-PARTY).

The bundled themes are inspired by and styled after the admonition designs of:

• GitHub: Alert syntax and visual style, colours from the Primer design system.
• Docusaurus: Admonition syntax and visual style, colours from the Infima CSS framework.
• MkDocs Material: Admonition design, colours from the Material Design palette.