Custom Admonition Classes in MyST and Jupyter Book

custom-admonitions.md

Custom Admonition Classes in MyST for Jupyter Book

I'm writing a Jupyter Book which presents mathematical theorems, and I'd like to have a special admonition for displaying lemmas and theorems.

This can be done by editing the sphinx configuration settings in _config.yml to include a path to your custom styles:

sphinx:
  config:
    html_css_files:
      - "_static/mystyle.css"

Then create the directory _static in your content directory (i.e. the same level as _config.yml), in which you can include your CSS files.

The mystyle.css file could look something like

.theorem {
    border-color:#c566df;
}
.admonition.theorem .admonition-title {
    background-color: #edddf4;
}
.admonition.theorem .admonition-title::before {
    color: #c566df;
    content: "T";
}

This not only changes the colour of the admonition, but also changes the symbol to be a capitol "T" instead of the info symbol.

We can now use this custom class with

:::{admonition} Some Title
:class: theorem

Some Content

:::

Build as normal with jb build, and it all should work!

Toggles in admonitions

I also like to include proofs in these theorem admonitions, and I would like these to be toggleable -- by default, the toggle blocks in MyST don't fit within the admonition block very nicely. To remedy this, I also add

.admonition p.admonition-title ~ * {
    right: +1em;
    padding: 0;
}

in the mystyle.css shift the toggle button left a little.

You can view an example of this in my WIP book on astrophysical topology.