Example of implementing a custom directive

[ronpandolfi]

I'm curious if anyone has implemented their own directives and injected them into the parser successfully. I sometimes find the built-in directives are insufficient, and have had interest in extending them.

For example, the figure directive doesn't seem to allow its image to also have a link. Extending that directive to add a link option spec would be useful to me. I'm also interested in completely custom directives.

Has this been described anywhere? The directive subclasses seem simple enough, but some guidance on how to inject them into the parser would help.

[michaelosthege]

I believe this should be covered by https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#directives-a-block-level-extension-point

[felixchenier]

Hi
I don't know if this is what the op meant, I think it is more "how to create custom directives". I also have this question, I think it would help me separating further text from formatting.

For example, I'm writing a website with tutorials, code examples, exercises, etc. I think it would be benefit for me to be able to do something like:

:::{exercise}
Question, [...]
:::

:::{todo}
This section should explain this or that better
:::

:::{goodpractice}
Usually you should do this or that
:::

At the moment I walked around by using admonitions and margins directly (see below), and by styling admonitions. It works wonderfully, but I think it's slightly less "robust": if I made a typo in 'Good practice', it would generate an unstyled admonition instead of expectedly failing; or if I forget that todos are in margin and I put it in admonition instead, it would silently generate discrepancies in styling.

:::{admonition} Exercise
Question, [...]
:::

:::{margin} todo
This section should explain this or that better
:::

:::{admonition} Good practice
Usually you should do this or that
:::

I'm pretty sure that creating custom directives is doable but I can't find a step-by-step method to do it.

Still, even this "kinda workaround" rocks, the whole Executable Book project is so awesome, thank you so much.

[choldgraf]

Here is one writeup in the EBP forum on defining custom admonitions (e.g. {goodidea}), does that help (cc @felixchenier)?

• https://github.com/orgs/executablebooks/discussions/655

You could also implement a much more complex directive by creating your own Sphinx extension. This is definitely non-trivial but would give you total flexibility over the document structure etc. In that case, I'd look at the extensions defined in the EBP ecosystem to get inspiration for what is possible.

[ronpandolfi]

Yes, this is the kind of thing I'm looking for. I see now that the directives are defined in docutils.parsers.rst.directives, and subclassing them gives me flexibility I'd want. Big thanks @choldgraf !

[felixchenier]

@choldgraf This is exactly what I needed. Thank you so much!