Update admonitions, making title optional

[julieg18]

• makes title optional, taking it off by default

Code Example:

<admon>

I don't need a title since I'm just a block of text.

</admon>

<admon title="Custom Title" type="tip">

I need a custom title for some reason

</admon>

Result:

Fixes #3381

[rogermparent]

Looks nice! I'm not sure if this is exactly what @shcheklein was thinking, but the option for an alternate minimal admonition seems pretty useful. I could see possible concerns around consistency between the two, though.

[julieg18]

Looks nice! I'm not sure if this is exactly what @shcheklein was thinking, but the option for an alternate minimal admonition seems pretty useful. I could see possible concerns around consistency between the two, though.

We could take off the title entirely! I wasn't sure which (asked in #3381), but for now, I made it an option 🤔

[daavoo]

I think the title might be useful on some occasions.

[jorgeorpinel]

Leaving title optional can't hurt. What I'm not sure we need is the default titles e.g. "Warning" in the description usage example. I think if title is used, a value should be provided, otherwise the syntax looks a bit strange to me.

[iesahin]

Could we make the titles similar to <details> block? Instead of adding it as an attribute, we could update the text itself like:

<admon type="tip">

## Very important tip

This is very important

</admon>

This is for the sake of consistency. I don't see the current way as particularly useless and if this is too much work, we can postpone it.

[jorgeorpinel]

make the titles similar to <details> block?

We're actually trying to make <details> work like <admon> instead @iesahin 😅 . See #3388

[iesahin]

Ah yeah, I noticed that after writing this. I think it's better to have the titles as first elements as in current details, it makes it easier to change details/admon to a standard section.

For linking there may be a slug or anchor attribute in the tag apart from the title. We can use it for linking. This also relaxes us to come up with very short titles for these sections.

[julieg18]

Leaving title optional can't hurt. What I'm not sure we need is the default titles e.g. "Warning" in the description usage example. I think if title is used, a value should be provided, otherwise the syntax looks a bit strange to me.

Good point! I'll take off the default title option!

As for using a title attribute vs taking a ### heading from the content, both are easily doable. I'm not sure which one is better... @jorgeorpinel, @iesahin since the original intent of this pr is to fix #3381, should we go ahead and merge this then discuss the title vs ### heading in a separate issue?

[jorgeorpinel]

For linking there may be a slug or anchor attribute
discuss the title vs ### heading in a separate issue

We're discussing that in #3383 , feel free to mention your idea there @iesahin (may be the easiest way indeed).

[jorgeorpinel]

Assuming default title has been removed. Thanks @julieg18