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.

🙌 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

1.0.5 (2024-04-18)

Features

• add util to check whether type is valid GitHub alert type (de20d72)
• simplify code and rename file to function name (2ba5d63)
• simplify code and return semantically correct type (c66d99c)
• use new return value in plugin (ddb6eb9)