Add admonitions/callout support to markdown/mdx

[lloydjatkinson]

Summary

"admonitions", callouts, notes, warnings and the like are common enough in markdown/mdx and I think it would be great if Astro could natively support this allowing Astro components to be mapped to user specified admonitions.

I believe that the bulk of this work has already been implemented in Starlight, can that be brought into core?

Background & Motivation

Currently, the closest feature is to use mdx and import a component like this:

import Tip from '@components/Tip.astro'

<Tip>
Something something dark side
</Tip

However this is sometimes adds more friction than desirable:

• We need to remember to import it (unless you setup a global component list)
• For the most part it's just easier to type ::: than angle brackets
• Admonitions are super common already, and this is an opportunity to provide a simpler content editing experience
• VSCode and other editors already have specific extensions for markdown admonitions such as https://marketplace.visualstudio.com/items?itemName=TomasDahlqvist.markdown-admonitions

This has previously been mentioned in #424 and #825.

Goals

A concise, bulleted-list outlining the intended goals of this RFC.

• Provide a nicer and more familiar editing experience users of other frameworks are already used to
• Migrate the current Starlight admonitions feature into Astro core/markdown/mdx
• Allow users to configure a mapping of admonition to Astro component
• Admonitions work universally across markdown and mdx files
• Support custom titles like Starlight does :::tip[Did you know?]

Example

I propose that astro.config.ts file has an option such as the following.

import Tip from '@components/Tip.astro';
import Danger from '@components/Danger.astro';

export default defineConfig({
    markdown: {
        admonitions: [
            'tip': Tip,
            'danger': Danger
        ]
    },
});

Remaining questions

This has some design decisions that need making:

• What format should be supported? Should it be the common :::tip or the recent GitHub added format > [!TIP]? Personally I prefer the ::: format.
• Should a format be imposed or user defined anyway? 'tip': Tip or ':::tip': Tip, in the config? I suspect imposing a format would lead to less complexity with remark/rehype.
• Should this support loading client framework components? I suspect this one needs some thought, considering mdx files are required whereas admonitions should work in both markdown and mdx. It may be just less complex to restrict this to Astro components (where users would be free to use their client framework components in them (I think?)). Probably the only practical option here is to only allow this RFC for mdx files.
• Markdoc support? I'm not familiar with this, so need input on that.

[stereobooster]

related: #423

[isimmons]

For plain MD it would be nice to choose our MD flavor. I'd like to be able to write GFM along with callouts/admonitions that view correctly on GitHub and then be able to pull those MD files into an app and render HTML without having to go through and modify to a different syntax.

[EricDriussi]

As nothing more than a user, I would suggest/kindly ask to stay with the common :::tip syntax rather than the GH format since it's simpler to read (which is kind of the point of markdown) and much more common.

Also, user defined format sounds nice, but it seems more complex and I would expect it to cause many more non-bug reports due to user error than the alternative. Maybe imposing a format would make for an easier first approach?

Just my two cents, looking forward to having support for this built-in.