remark-github-admonitions-to-directives

Remark Github Alerts to Directives

💫 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:

> [!NOTE]
> Content

Into this:

:::note
Content
:::

💾 Installation

You can install this plugin with:

pnpm 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)

import { remark } from "remark";
import remarkDirective from "remark-directive";
import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";

const processor = remark()
  .use(remarkGithubAdmonitionsToDirectives)
  .use(remarkDirective);

const result = processor.processSync(`
> [!NOTE]
> content
`);

console.log(result.toString());

// should output:
// :::note
// content
// :::

🦖 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:

import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";

export default {
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          path: "docs",
          beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives],
        },
      },
    ],
  ],
};

[!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:

import { remark } from "remark";
import remarkDirective from "remark-directive";
import remarkGithubAdmonitionsToDirectives, {
  DEFAULT_MAPPING,
  DirectiveName,
  GithubAlertType,
  type AlertTypeMapping,
} from "remark-github-admonitions-to-directives";

const mapping: AlertTypeMapping = {
  ...DEFAULT_MAPPING,
  [GithubAlertType.IMPORTANT]: DirectiveName.WARNING,
};

const processor = remark()
  .use(remarkGithubAdmonitionsToDirectives, { mapping })
  .use(remarkDirective);

const result = processor.processSync(`
> [!IMPORTANT]
> content
`);

console.log(result.toString());

// should output:
// :::info
// content
// :::

🙌 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.

Changelog

2.1.0 (2024-10-28)

Features

• allow customizing the alert type to admonitions directive mapping via the plugin options (6605a88)