💫 Introduction

Github introduced alerts in markdown files with their own proprietary syntax instead of using Remark directives. This plugin converts Github's blockquote alert style to Remark admonitions syntax.

It will transform this:

1> [!NOTE]
2> Content

Into this:

1:::note
2Content
3:::

💾 Installation

You can install this plugin with:

1pnpm add -D remark-github-admonitions-to-directives

🪛 Usage

This plugin is just a generic unified (remark) plugin to transform one syntax into another. Below are some examples of how to use it with various plugins / systems:

📃 With Remark (and Directives)

1import { remark } from "remark";
2import remarkDirective from "remark-directive";
3import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";
4
5const processor = remark()
6  .use(remarkGithubAdmonitionsToDirectives)
7  .use(remarkDirective);
8
9const result = processor.processSync(`
10> [!NOTE]
11> content
12`);
13
14console.log(result.toString());
15
16// should output:
17// :::note
18// content
19// :::

🦖 With Docusaurus

Admonitions are a core feature of Docusaurus and this plugin was actually built with the use case of reusing markdown files, written with Github's syntax, in Docusaurus.

To use this plugin, just use the instructions for adding MDX plugins and add this plugin to the beforeDefaultRemarkPlugins section of your docusaurus.config.js file:

1import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";
2
3export default {
4  presets: [
5    [
6      "@docusaurus/preset-classic",
7      {
8        docs: {
9          path: "docs",
10          beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives],
11        },
12      },
13    ],
14  ],
15};

[!IMPORTANT] Because this plugin converts Github's syntax to the directives syntax, and Docusaurus then uses the directives syntax to create the adminitions, this plugin has to be processed before any of the Docusaurus plugins. This is why it's added to the beforeDefaultRemarkPlugins array and not the remarkPlugins array.

⚙️ Customizing the mapping

By default, this plugin will map the Github alerts to the Remark admonitions as follows:

• NOTE -> note
• TIP -> tip
• WARNING -> warning
• IMPORTANT -> info
• CAUTION -> danger

If you want to customize this mapping, you can pass an object with the mapping to the plugin:

1import { remark } from "remark";
2import remarkDirective from "remark-directive";
3import remarkGithubAdmonitionsToDirectives, {
4  DEFAULT_MAPPING,
5  DirectiveName,
6  GithubAlertType,
7  type AlertTypeMapping,
8} from "remark-github-admonitions-to-directives";
9
10const mapping: AlertTypeMapping = {
11  ...DEFAULT_MAPPING,
12  [GithubAlertType.IMPORTANT]: DirectiveName.WARNING,
13};
14
15const processor = remark()
16  .use(remarkGithubAdmonitionsToDirectives, { mapping })
17  .use(remarkDirective);
18
19const result = processor.processSync(`
20> [!IMPORTANT]
21> content
22`);
23
24console.log(result.toString());
25
26// should output:
27// :::info
28// content
29// :::

🙌 Contributing

This plugin was created and is maintained by Incentro. If you're running into issues, please open an issue. If you want to contribute, please read our contributing guidelines.