# 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/pedagogical admonitions for Material for MkDocs.

It includes automatic numbering, collapsible admonitions, six built-in locales, localized aliases and proof endings, independent Light/Dark appearance values, monochrome or multicolor icons, Material instant-navigation support, and an explicit Reveal.js API.

## Links

- Documentation and live examples: https://rod2ik.gitlab.io/mkdocs-maths-admonitions/
- Source: https://gitlab.com/rod2ik/mkdocs-maths-admonitions
- npm: https://www.npmjs.com/package/@rod2ik/mkdocs-maths-admonitions
- jsDelivr: https://www.jsdelivr.com/package/npm/@rod2ik/mkdocs-maths-admonitions

## Main features

- 34 canonical built-in admonitions;
- standard `!!!` and collapsible `???` / `???+` syntax;
- one automatic counter per canonical type;
- global, per-type and local numbering controls;
- English, French, Spanish, Italian, German and Portuguese catalogues;
- localized labels, aliases and QED/CQFD/CQD/CVD/WZBW proof endings;
- common + Light/Dark colors, borders, backgrounds, icons and font sizes;
- `iconMode: "mask"` and `iconMode: "image"`;
- custom site admonitions and project tooling for new built-ins;
- Material instant navigation;
- `initReveal()` for Reveal.js decks.

The complete behavior and configuration reference lives on the documentation site; the README intentionally stays concise instead of duplicating it.

## Installation

Enable Material's admonition extensions:

```yaml
markdown_extensions:
  - admonition
  - pymdownx.details
```

Then load an optional configuration file **before** MMA:

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

Example `docs/javascripts/maths-admonitions.config.js`:

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

The JavaScript automatically loads its matching stylesheet unless `styles.autoLoad` is disabled. Explicit CSS and Material `overrides/main.html` installation methods are documented under [Installation](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/installation/).

## Markdown examples

Standard:

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

Collapsible, initially closed:

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

Collapsible, initially open:

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

Localized aliases resolve to canonical keys. For example, with the French locale, `automatisme` resolves to the canonical `automaticity` type. Configuration should normally use canonical keys.

## Configuration example

```js
window.MkDocsMathsAdmonitionsConfig = {
  locale: "fr",

  numbering: {
    enabled: true
  },

  admonitions: {
    theorem: {
      color: "#1565c0"
    },

    proof: {
      numbered: false,
      iconColorLight: "#000000",
      iconColorDark: "#ffffff"
    }
  }
};
```

See the documentation for the full appearance priority rules, numbering precedence, local `[number]` / `[no-number]` markers, aliases, custom locales, proof-ending images, special styles and advanced project extensions.

## Browser API

The bundle exposes:

```js
window.MkDocsMathsAdmonitions
```

with:

```text
version
 defaults
 supportedLocales
 themes
 iconModes
 themeAwareProperties
 getConfig()
 loadStyles()
 init()
 refresh()
 initReveal()
```

See the [Runtime API](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/reference/api/).

## Development

Requirements include Node.js 20.19+ and Yarn 4.17.1 through Corepack.

Normal validation loop:

```bash
corepack enable
yarn install --immutable
yarn bfc
yarn dev
```

Main commands:

```text
yarn dev / yarn dev:lan
yarn build
yarn build:full
yarn build:full:check
yarn bfc
yarn vendor:sync / vendor:check / vendor:clean
yarn admonitions:check / admonitions:list / admonition:add
yarn zip
```

The MkDocs site uses the current locally built MMA distribution in both local development and GitLab Pages. TikZJax is used only by a documentation integration example and is pinned separately in `vendor.config.mjs`.

See [Development](https://rod2ik.gitlab.io/mkdocs-maths-admonitions/development/) for the complete workflow.

## Versioning and publishing

`package.json` is the **single source of truth** for the project version.

For a new version:

```text
1. edit only package.json version
2. yarn bfc
3. commit and push main
4. after the main pipeline is green:
   git tag vX.Y.Z
   git push origin vX.Y.Z
```

GitLab CI checks that the tag equals `v` + `package.json.version`, publishes npm from the tagged commit, and then creates the GitLab Release.

## License

GNU General Public License v3.0 or later. See [LICENSE](LICENSE).