Simplified Admonition Titles

[rowanc1]

📖 Read the MEP Here

We propose a simplified syntax to allow arguments for all named admonitions. The syntax allows an argument for any title of a named admonition like {tip} or {note}, to allow users to easily set the color and icon of an admonition while also having a custom title. The proposed syntax is:

```{note} Custom Note Title
Body of the styled admonition.
```

Coauthored with @mmcky.

See also:

• Collection of pointers for Admonitions improvements myst-spec#49

TODO:

• Merge cross references, turn that to active MEP0002!
• Another pass on the document, cleaning up any ideas
• Get images into a local folder
• discuss MEP codemods and how to do this, update that section

[chrisjsewell]

So, to be frank, I feel it will be impossible to make this change in https://github.com/executablebooks/MyST-Parser:
it would break too much, without any deprecation route.

As discussed in jupyter-book/myst-spec#57, I do think it would be possible with div though, i.e.

:::{note} Custom Note Title
Body of the styled admonition.
:::

[chrisjsewell]

With div it would be possible, because the current colon_fence is a syntax extension:
We could detect if a user has set colon_fence, and if so issue a warning, saying they should change to div, and providing a URL link to a page explaining the difference

I would also suggest with div, we may want to think about (a) no longer using :a: b to denote options, and instead using block attributes, and (b) introducing a leaf div

So instead of

:::{name}
:class: class
:name: name
:key: value

Content
:::

it could be

{#name .class key=value}
:::{name}
Content
:::

or even

{#name .class key=value}
::{name} Content

the key thing here obviously being terseness of the syntax

[rowanc1]

Ok, I didn't understand the different code paths between a fence and a code block on the python/docutils side. For JS there isn't an issue at all.

I think that really high-grades the colon-fence MEP. Happy to have the colon fence be the documented/only way to do this, the only reason I used backticks here is because that isn't in the myst-spec at all yet.

Let's use #13 to track that, and then move onto #10.

[chrisjsewell]

Yep, as mentioned in executablebooks/MyST-Parser#713

I feel the key difference here is that:

• ``` fence should be for enclosing non-myst content
• ::: div should be for enclosing myst content

[chrisjsewell]

(Happy to jump on a chat to discuss this with you guys 😄 )

[chrisjsewell]

Note, one thing that is maybe problematic about {#name .class key=value} though, is if you need a flag, like

:::{name}
:flag:
:::

e.g. this is not currently valid attribute syntax {flag}, so at resent you would have to do something like {flag=true}

[mmcky]

Yep, as mentioned in executablebooks/MyST-Parser#713

I feel the key difference here is that:

• ``` fence should be for enclosing non-myst content
• ::: div should be for enclosing myst content

hey @chrisjsewell @rowanc1 I am not sure I fully understand this point / discussion.

It would be great to link up at some point to fully explore this.

My concern here is that from a user perspective -- they really shouldn't need to know the difference between myst and non-myst content in my mind. To me we have an entry point into directives which represents -- do something special with whatever is in here.

[chrisjsewell]

My concern here is that from a user perspective -- they really shouldn't need to know the difference between myst and non-myst content in my mind. To me we have an entry point into directives which represents -- do something special with whatever is in here.

Except, I would suggest, many people do. ::: containers were heavily requested, in particular as a way to have admonitions (or really any directive containing Markdown) render correctly in "non-myst" environments (like here on GitHub).
That, plus it makes it a lot more friendly for static anlysers (like syntax highlighters and LSPs) to assess the source text, without having knowledge of every possible directive

If we do a quick GitHub search: https://github.com/search?q=%5C%22colon_fence%5C%22&type=code
there are 1200 hits

By contrast, and I'm happy to be proved otherwise, I've had very few people ask for what this MEP proposes;
it's more of a nice to have.

and yeh to re-iterate, this MEP is essentially suggesting changing the whole semantics of ``` directive parsing, to improve one use-case.
Plus, in a way that would likely break many myst-parser projects and, more critically, it would break them in a way that is really difficult/impossible to detect, warn about and provide deprecation pathways

[tavin]

As a random end user stumbling across this let me remark that @chrisjsewell's direction sounds good to me. I had the wish already that anything in a colon fence would be rendered as markdown, period, and never as preformatted code.