# MkDocs Maths Admonitions

[![npm version](https://img.shields.io/npm/v/%40rod2ik%2Fmkdocs-maths-admonitions?logo=npm)](https://www.npmjs.com/package/@rod2ik/mkdocs-maths-admonitions)
[![npm downloads](https://img.shields.io/npm/dm/%40rod2ik%2Fmkdocs-maths-admonitions?logo=npm)](https://www.npmjs.com/package/@rod2ik/mkdocs-maths-admonitions)
[![License](https://img.shields.io/npm/l/%40rod2ik%2Fmkdocs-maths-admonitions)](LICENSE)
[![GitLab pipeline](https://img.shields.io/gitlab/pipeline-status/rod2ik/mkdocs-maths-admonitions?branch=main&logo=gitlab&label=build)](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/pipelines)
[![Documentation](https://img.shields.io/website?url=https%3A%2F%2Frod2ik.gitlab.io%2Fmkdocs-maths-admonitions%2F&label=documentation)](https://rod2ik.gitlab.io/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](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/)           |
| Source repository                         | [rod2ik/mkdocs-maths-admonitions](https://gitlab.com/rod2ik/mkdocs-maths-admonitions)                     |
| npm package                               | [@rod2ik/mkdocs-maths-admonitions](https://www.npmjs.com/package/@rod2ik/mkdocs-maths-admonitions)        |
| jsDelivr CDN                              | [@rod2ik/mkdocs-maths-admonitions](https://www.jsdelivr.com/package/npm/@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`:

```yaml
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`:

```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](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/installation/).

## Basic Markdown

Standard admonition:

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

Collapsible admonition, initially closed:

```markdown
??? proof
    The proof is initially hidden.
```

Collapsible admonition, initially open:

```markdown
???+ example
    This example is initially visible.
```

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

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

The canonical key of this admonition remains:

```text
automaticity
```

## Examples

### i18n Collapsible Admonitions

#### English — Proof / QED

![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/enProofLight.png)
![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/enProofDark.png)

#### Français — Démonstration / CQFD

![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/frProofLight.png)
![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/frProofDark.png)

#### Español — Demostración / CQD

![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/esProofLight.png)
![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/esProofDark.png)

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

![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/enAlgorithmLight.png)
![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/enAlgorithmDark.png)

#### Français

![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/frAlgorithmLight.png)
![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/frAlgorithmDark.png)

#### Español

![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/esAlgorithmLight.png)
![](https://gitlab.com/rod2ik/mkdocs-maths-admonitions/-/raw/main/assets/img/esAlgorithmDark.png)

Additional locale examples are available on the documentation site.

## Built-in admonitions

The registry contains 34 canonical admonitions:

```text
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:

```text
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:

```text
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:

```js
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:

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

These structural options remain theme-independent:

```text
enabled
numbered
start
separator
style
iconMode
```

The complete appearance reference is available in the
[Appearance documentation](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/appearance/).

## Localized proof endings

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

```text
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](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/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:

```yaml
---
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](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/)
- [Appearance](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/appearance/)
- [Behavior and numbering](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/behavior/)
- [Aliases and localization](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/localization/)
- [Advanced customization](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/advanced/)

## 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

```bash
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:

```bash
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](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/configuration/advanced/).

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

```bash
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:

```text
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:

```text
site/overrides/vendor/
```

Files written specifically for the documentation site remain separate:

```text
site/overrides/javascripts/
site/overrides/stylesheets/
```

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

```text
site/overrides/
```

### Development site

Start the live development site:

```bash
yarn dev
```

Then open:

```text
http://127.0.0.1:8000
```

A complete production documentation build is generated with:

```bash
yarn build:full
```

The resulting GitLab Pages site is written to:

```text
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](LICENSE).

## Developer

Developed and maintained by
[Rodrigo Schwencke (Rod2ik)](https://gitlab.com/rod2ik).