incentro-dcRemark 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]
> ContentInto 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
beforeDefaultRemarkPluginsarray and not theremarkPluginsarray.
⚙️ Customizing the mapping
By default, this plugin will map the Github alerts to the Remark admonitions as follows:
NOTE->noteTIP->tipWARNING->warningIMPORTANT->infoCAUTION->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.