Support directive-based admonitions and alerts for mdx and md sources

[cameronraysmith]

What problem will this feature address?

Several widely-used markdown extensions such as those in

• https://docusaurus.io/docs/3.3.2/markdown-features/admonitions
• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
• https://vitepress.dev/guide/markdown#github-flavored-alerts

use directives or other syntax to support alerts, admonitions, etc.

examples of directive-based admonition/alert syntax that may be used in md(x) taken from the docusaurus docs

:::note

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::tip

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::info

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::warning

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::danger

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

Describe the solution you'd like

It would be helpful to support github-flavored markdown or mdx files that contain this style of alert or directive-based admonition syntax.

Describe alternatives you've considered

fumadocs already supports this via components in mdx for example

import { Callout } from "fumadocs-ui/components/callout";

<Callout type="info">
  Information
</Callout>

<Callout type="warn">
  Warning
</Callout>

...

however, I am not sure if there is a built-in approach to translate the directive syntax like that utilized by docusaurus to Callout components using a custom MDX -> JSX transform function with a content-collection source for mdx.

It should also be possible to use remark plugins

• https://github.com/remarkjs/remark-directive
• https://github.com/incentro-dc/remark-github-admonitions-to-directives

together with appropriate styles to support this with markdown if there is not already a simpler approach I am not aware of. This could be facilitated by a complementary content-collection MD -> HTML transform function for markdown

[cameronraysmith]

If it helps to understand where this was identified, I encountered this in exploring approaches that might help to use content-collections to translate the quarto qmd format to mdx, md, or html compatible with fumadocs.

[fuma-nama]

I personally avoid these syntax as it is not the standard of CommonMark and MDX, but JSX is. I think we can offer a rehype plugin for people migrating from other docs frameworks as JSX (using the component directly) is more flexible and friendly.

In MDX, intellisense works for directly imported components which makes it significantly easier to use.

[cameronraysmith]

I agree. For my use case it's probably better to just write a pandoc lua filter | like this one for docusaurus that specifically targets translation to fumadocs-compatible Callout components in MDX wherever the source markdown uses directive syntax. I will close this as I think that will likely be a better solution and shouldn't require any change to fumadocs. Many thanks!