在 Astro 添加 markdown 提示语法 • Usubeni Fantasy

简单的前情提要一下吧，就是想在自己博客里实现 Docusaurus 的 admonition（甚至是更换框架的直接原因），今天终于集成进来啦！先给出最终方案，其他方案在后面，FYI。

最终方案

GitHub 的提示方案，最大优势是可以直接在 Github 显示正确格式。

因为 remark 社区已实现插件，所以集成到 Astro 只需要一些简单操作（不用像 Gatsby 那样再套一层真的太舒服了）：

import { defineConfig } from "astro/config";

const raConfig = {
  classNameMaps: {
    block: (title: string) => "admonition " + title.toLowerCase(),
    title: "admonition-title",
  },
  titleFilter: (title: string) => {
    return title.match(/\[![^\]]+\]/g);
  },
};

export default defineConfig({
  // 省略
  markdown: {
    remarkPlugins: [
      remarkMath,
      remarkUnwrapImages,
      remarkReadingTime,
      // @ts-expect-error:next-line
      [remarkAdmonitions, raConfig],
    ],
  },
  // 省略
});

实现效果：

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

> [!其他]
> 其他没识别到的标签，通用灰色

> 普通引用

NOTE

Highlights information that users should take into account, even when skimming.

TIP

Optional information to help a user be more successful.

IMPORTANT

Crucial information necessary for users to succeed.

WARNING

Critical content demanding immediate user attention due to potential risks.

CAUTION

Negative potential consequences of an action.

其他

其他没识别到的标签，通用灰色

普通引用

其他方案

在这次调研中，我还找到了不少其他提示语法方案，在之前的博文也提到了一些，这里再整理一下更完整的版本。

remark-admonitions

https://github.com/elviswolcott/remark-admonitions

现时比较常见的语法（大概是被 Docusaurus 推广的）。

:::keyword optional title
some content
:::

remark-directive

https://github.com/remarkjs/remark-directive

更具拓展能力，可以随意设定标签和 class：

:::main{#readme}

Lorem:br
ipsum.

::hr{.red}

A :i[lovely] language know as :abbr[HTML]{title="HyperText Markup Language"}.

:::

callout

使用 MARKDOC 的 callout 转换自定义标签：

{% callout title="Hey you!" icon="note" %}
I have a message for you
{% /callout %}

commonmark-ext-notifications

https://github.com/McFoggy/commonmark-ext-notifications

! This is an info message.
!v This is a success message.
!! Consider this a warning.
!x This is an error message.