MkDocs Maths Admonitions

MkDocs Maths Admonitions (MMA) provides configurable and internationalized mathematical admonitions for Material for MkDocs.

It includes automatic numbering, standard and collapsible admonitions, localized labels and aliases, independent Light/Dark appearance settings, monochrome and multicolor icon modes, and localized proof-ending symbols.

In the examples below, replace __MMA_VERSION__ with the latest published version.

Documentation Site & Project URLs

| Resource | Link | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Documentation and live demonstration site | rod2ik.gitlab.io/mkdocs-maths-admonitions | | Source repository | rod2ik/mkdocs-maths-admonitions | | npm package | @rod2ik/mkdocs-maths-admonitions | | jsDelivr CDN | @rod2ik/mkdocs-maths-admonitions |

Main features

• 34 built-in mathematical and pedagogical admonitions;
• automatic numbering with one independent counter per canonical type;
• global and per-admonition numbering options;
• local [number] and [no-number] markers;
• standard, initially closed and initially open collapsible admonitions;
• six built-in localization catalogues;
• canonical language-independent keys and localized Markdown aliases;
• global and page-specific locales;
• localized QED, CQFD, CQD, CVD and WZBW proof endings;
• common, Light and Dark colors, borders, backgrounds, icons and font sizes;
• monochrome CSS-mask icons;
• multicolor image icons with preserved colors and transparency;
• site-specific custom admonitions;
• project tooling for adding and validating built-in admonitions;
• Material instant-navigation and Reveal.js support.

Installation

Enable the standard MkDocs admonition extensions, then load the optional MMA configuration file before the library.

The library automatically loads its matching stylesheet, so no extra_css entry is required for this basic installation.

Add the following entries to mkdocs.yml:

markdown_extensions:
  - admonition
  - pymdownx.details

extra_javascript:
  - javascripts/maths-admonitions.config.js
  - https://cdn.jsdelivr.net/npm/@rod2ik/mkdocs-maths-admonitions@__MMA_VERSION__/dist/mkdocs-maths-admonitions.min.js

Create docs/javascripts/maths-admonitions.config.js:

window.MkDocsMathsAdmonitionsConfig = {
  locale: "en"
};

The configuration file is optional. When the built-in defaults are sufficient, remove its entry from extra_javascript and load only the main library.

The complete installation methods, including explicit CSS loading and Material theme overrides, are described in the installation documentation.

Basic Markdown

Standard admonition:

!!! theorem
    Every finite subgroup of the multiplicative group of a field is cyclic.

Collapsible admonition, initially closed:

??? proof
    The proof is initially hidden.

Collapsible admonition, initially open:

???+ example
    This example is initially visible.

A localized alias can be used when its locale is active:

!!! automatisme
    Compute mentally: $7 \times 8 = 56$.

The canonical key of this admonition remains:

automaticity

Examples

i18n Collapsible Admonitions

English — Proof / QED

Français — Démonstration / CQFD

Español — Demostración / CQD

Additional locale examples are available on the documentation site.

i18n Non-collapsible Admonitions

The following deliberately exaggerated examples demonstrate some of the available customization options.

English

Français

Español

Additional locale examples are available on the documentation site.

Built-in admonitions

The registry contains 34 canonical admonitions:

algorithm
anecdote
automaticity
axiom
challenge
conjecture
consequence
construction
corollary
correction
counterexample
definition
example
exercise
film
hint
hypothesis
iremember
lemma
method
notation
problem
problematic
proof
property
proposition
python
reference
remark
reminder
response
summary
theorem
thesis

Canonical keys are language-independent. For example, the French alias automatisme resolves to automaticity, while preuve resolves to proof.

Theme-aware appearance

Every visual component can use one common value plus optional Light and Dark overrides:

color / colorLight / colorDark
borderColor / borderColorLight / borderColorDark
backgroundColor / backgroundColorLight / backgroundColorDark
iconColor / iconColorLight / iconColorDark
icon / iconLight / iconDark
fontSize / fontSizeLight / fontSizeDark

A common value applies to both themes. A theme-specific value overrides it only for that theme.

User configuration has priority over built-in values, including when a common user value replaces built-in Light and Dark variants.

When only iconLight or only iconDark is supplied and no common icon exists, that image is reused in both themes.

Icon rendering modes

Title icons support two rendering modes:

iconMode: "mask"   → use the image as a monochrome CSS mask
iconMode: "image"  → preserve the image's original colors and transparency

mask is the default mode. The image supplies the shape, while iconColor, iconColorLight and iconColorDark supply its visible color.

Example:

window.MkDocsMathsAdmonitionsConfig = {
  locale: "fr",

  admonitions: {
    proof: {
      color: "#757575",
      borderColor: "#aaaaaa",
      backgroundColor: "rgba(127, 127, 127, 0.25)",
      icon: "proof.svg",
      iconColorLight: "#000000",
      iconColorDark: "#ffffff",
      iconMode: "mask"
    }
  }
};

A multicolor image can preserve its original appearance:

window.MkDocsMathsAdmonitionsConfig = {
  admonitions: {
    python: {
      icon: "python.svg",
      iconMode: "image"
    }
  }
};

These structural options remain theme-independent:

enabled
numbered
start
separator
style
iconMode

The complete appearance reference is available in the Appearance documentation.

Localized proof endings

The canonical proof admonition can display a localized proof-ending symbol:

QED
CQFD
CQD
CVD
WZBW

The locale catalogue can select independent Light and Dark SVG resources.

Proof-ending symbols are rendered separately from title icons:

• the selected shape is black in Light mode;
• the selected shape is white in Dark mode;
• transparent areas remain transparent;
• Light and Dark files may contain different shapes;
• the internal SVG colors are ignored during display.

The complete catalogue structure, fallback rules and site-specific customization method are documented in Aliases & Localization.

Internationalization

English is the default language. Built-in catalogues are provided for:

• English (en);
• French (fr);
• Spanish (es);
• Italian (it);
• German (de);
• Portuguese (pt).

A locale controls:

• generated labels;
• accepted localized aliases;
• localized proof-ending symbols.

One page can override the global locale with:

---
mma_locale: fr
---

Local configuration may add aliases without removing official aliases or replacing official labels.

Re-adding an official alias to the same admonition is harmless. An alias collision between two different admonitions produces a console warning, and the conflicting addition is ignored.

Configuration documentation

• Configuration overview
• Appearance
• Behavior and numbering
• Aliases and localization
• Advanced customization

Development

Requirements

The project is built with Yarn 4, Vite, JavaScript, SCSS and sass-embedded.

• Node.js 20.19 or newer;
• Yarn 4.17.1 through Corepack;
• MkDocs 1.x;
• Material for MkDocs 9.x.

Main commands

yarn install
yarn dev
yarn build
yarn build:full
yarn build:full:check
yarn bfc
yarn test
yarn admonitions:check
yarn admonitions:list
yarn admonitions:list fr
yarn pack
yarn deploy

Adding a built-in admonition

The minimum command requires a canonical key and an English label:

yarn admonition:add criterion \
  --label-en "Criterion"

A complete command may also define:

• translations and aliases for all six built-in locales;
• common, Light and Dark colors;
• common, Light and Dark icon resources;
• iconMode;
• font sizes;
• a structural style;
• automatic icon generation;
• numbered: false.

The complete workflow is documented in Advanced customization.

After adding or modifying a built-in admonition, run:

yarn admonitions:check
yarn bfc

Tests that intentionally assert the exact built-in registry size or exact asset filenames must also be updated when those expectations change.

Build outputs

The library build is generated in:

dist/
├── maths-admonitions.config.js
├── mkdocs-maths-admonitions.js
├── mkdocs-maths-admonitions.min.js
└── assets/
    ├── mkdocs-maths-admonitions.css
    ├── mkdocs-maths-admonitions.min.css
    └── img/

For the local MkDocs documentation, yarn build:full copies the complete dist/ directory to:

site/overrides/vendor/

Files written specifically for the documentation site remain separate:

site/overrides/javascripts/
site/overrides/stylesheets/

The Material theme templates and static documentation assets all live under:

site/overrides/

Development site

Start the live development site:

yarn dev

Then open:

http://127.0.0.1:8000

A complete production documentation build is generated with:

yarn build:full

The resulting GitLab Pages site is written to:

public/

License

MkDocs Maths Admonitions is free and open-source software distributed under the terms of the GNU General Public License v3.0 or later.

Developer

Developed and maintained by Rodrigo Schwencke (Rod2ik).