Minimal code to define a custom admonition

[choldgraf]

Description

Sometimes you want to be able to quickly define a new admonition that you plan to use throughout your documentation. For example, you might want to do this:

```{example} Doing a thing
Here's code that shows how to do a thing...
```

However, the {example} directive doesn't exist, so the only way to do this is via a custom {admonition} directive, like so:

```{admonition} Example: doing a thing
:class: tip  
Here's code that shows how to do a thing...
```

This is fine, but tedious, especially if you need to do this many times in your documentation.

Quickly define your own admonition directive

It is possible to quickly define your own directive that you can re-use throughout. Here's the minimal code that accomplishes the directive in the first example:

from docutils.parsers.rst.directives.admonitions import Admonition

class Example(Admonition):
    def run(self):
        # Manually add a "tip" class to style it
        if "class" not in self.options:
            self.options["class"] = ["tip"]
        else:
            self.options["class"].append("tip")
        # Add `Example` to the title so we don't have to type it
        self.arguments[0] = f"Example: {self.arguments[0]}"
        # Now run the Admonition logic so it behaves the same way
        nodes = super().run()
        return nodes

def setup(app):
    app.add_directive("example", Example)

This will allow you to do:

```{example} example title
Here's code that shows how to do a thing...
```

This results in:

Just thought I'd share here in case others found it useful, and as a reference that we can document if we get around to it (cc @mmcky )

[psychemedia]

This is really useful, Just a couple of other points to note for a minimal working example:

• in a new directory example, create a setup.py containing at least:

from setuptools import setup, find_packages

setup(
    name="custom-directive",
    packages=find_packages()
    )

• in example/custom-directive create __init__.py containing the example code;
• run pip install ./example
• add the extension to you Jupyter Book _config.yml file, for example:

sphinx:
  extra_extensions:
    - custom-directive

Build your Jupyter Book in the normal way.

[psychemedia]

Is there a similarly simple recipe for adding support to jupyterlab-myst?

[chrisjsewell]

I would reference your own issue 😉 jupyter-book/jupyterlab-myst#31

[tavin]

In light of recent developments re: colon fences and colon divs, and the issue of custom admonition titles, I hacked my parser to support the following syntax:

::: {!example} Doing a thing
Here's code that shows how to do a thing...
:::

Of course the hack does nothing but change the directive to {admonition} and pass the directive name through as a :class: option. With a little CSS you have nice HTML results very quickly.

Anyway it seems the framework really needs a more fluid mechanism for admonitions not foreseen in the spec. Maybe this could be the way?

[tavin]

That's very reasonable 👍

Lean syntax is crucial for markdown, but I guess there's no universal symbol that means "admonition" to everyone in the same way that > means "blockquote" to everyone.

I was trying to come up with a 2-3 letter alternative but all I have is box.

[chrisjsewell]

I was really quite tempted to add an emoji admonition extension to myst-parser (a la jgm/djot#196 (comment)) I think that would be quite cool 😆

[tavin]

That is a cool idea... and it already kinda works now? I mean, if higher unicode is allowed as a CSS class name...

::: 😆

Now tweak the parser a bit so that h1-h6 is allowed after the class...

::: 😆 # My admon title

[psychemedia]

Now wondering: how are emojis treated by screen readers? What keyboard support is needed to create emojis? etc.. (I never got past emoticons;-)

[tavin]

@chrisjsewell what if one of the following syntaxes were made to convert a div-with-class to an admonition?

::: class # Title

::: class | Title

::: class ! Title

[spring-haru]

@choldgraf Where am I supposed to put the following code you mentioned? Which directory?

from docutils.parsers.rst.directives.admonitions import Admonition

class Example(Admonition):
    def run(self):
        # Manually add a "tip" class to style it
        if "class" not in self.options:
            self.options["class"] = ["tip"]
        else:
            self.options["class"].append("tip")
        # Add `Example` to the title so we don't have to type it
        self.arguments[0] = f"Example: {self.arguments[0]}"
        # Now run the Admonition logic so it behaves the same way
        nodes = super().run()
        return nodes

def setup(app):
    app.add_directive("example", Example)