feat: allow customizing the alert type to admonitions directive mappi…

…ng via the plugin options (#9)

README.md

@@ -97,6 +97,50 @@ export default {
 > [!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:
+
+```typescript
+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](https://www.incentro.com/). If you're running into issues, please [open an issue](/~https://github.com/incentro-dc/remark-github-admonitions-to-directives/issues/new). If you want to contribute, please read our [contributing guidelines](./CONTRIBUTING.md).

src/alert-type-mapping.type.ts

@@ -0,0 +1,4 @@
+import type { DirectiveName } from "./directive-name.enum.js";
+import type { GithubAlertType } from "./github-alert.type.js";
+
+export type AlertTypeMapping = Record<GithubAlertType, DirectiveName | string>;

src/default-mapping.const.ts

@@ -0,0 +1,11 @@
+import type { AlertTypeMapping } from "./alert-type-mapping.type.js";
+import { DirectiveName } from "./directive-name.enum.js";
+import { GithubAlertType } from "./github-alert.type.js";
+
+export const DEFAULT_MAPPING: AlertTypeMapping = {
+  [GithubAlertType.NOTE]: DirectiveName.NOTE,
+  [GithubAlertType.TIP]: DirectiveName.TIP,
+  [GithubAlertType.WARNING]: DirectiveName.WARNING,
+  [GithubAlertType.IMPORTANT]: DirectiveName.INFO,
+  [GithubAlertType.CAUTION]: DirectiveName.DANGER,
+};

src/directive-name.enum.ts

@@ -0,0 +1,7 @@
+export enum DirectiveName {
+  NOTE = "note",
+  TIP = "tip",
+  WARNING = "warning",
+  INFO = "info",
+  DANGER = "danger",
+}

src/index.ts

@@ -1 +1,6 @@
+export type { AlertTypeMapping } from "./alert-type-mapping.type.js";
+export { DEFAULT_MAPPING } from "./default-mapping.const.js";
+export { DirectiveName } from "./directive-name.enum.js";
+export { GithubAlertType } from "./github-alert.type.js";
+export type { Options } from "./options.type.js";
 export { remarkGithubAdmonitionsToDirectives as default } from "./plugin.js";

src/options.type.ts

@@ -0,0 +1,5 @@
+import type { AlertTypeMapping } from "./alert-type-mapping.type.js";
+
+export type Options = {
+  mapping?: AlertTypeMapping;
+};

src/plugin.test.ts

@@ -1,6 +1,10 @@
 import { remark } from "remark";
 import remarkDirective from "remark-directive";
 import { describe, expect, it } from "vitest";
+import type { AlertTypeMapping } from "./alert-type-mapping.type.js";
+import { DEFAULT_MAPPING } from "./default-mapping.const.js";
+import { DirectiveName } from "./directive-name.enum.js";
+import { GithubAlertType } from "./github-alert.type.js";
 import { remarkGithubAdmonitionsToDirectives } from "./plugin.js";
 
 async function process(input: string): Promise<string> {
@@ -86,4 +90,77 @@ describe("remark-github-admonitions-to-directives", () => {
       "
     `);
   });
+
+  it("should allow customizing the directive mapping via the options", async () => {
+    const input = `
+> [!NOTE]
+
+> [!TIP]
+
+> [!IMPORTANT]
+
+> [!WARNING]
+
+> [!CAUTION]
+    `;
+
+    const mapping: AlertTypeMapping = {
+      [GithubAlertType.NOTE]: DirectiveName.DANGER,
+      [GithubAlertType.TIP]: DirectiveName.WARNING,
+      [GithubAlertType.IMPORTANT]: DirectiveName.TIP,
+      [GithubAlertType.WARNING]: DirectiveName.INFO,
+      [GithubAlertType.CAUTION]: DirectiveName.NOTE,
+    };
+
+    const file = await remark()
+      .use(remarkGithubAdmonitionsToDirectives, { mapping })
+      .use(remarkDirective)
+      .process(input);
+
+    const result = file.toString();
+
+    expect(result).toMatchInlineSnapshot(`
+      ":::danger
+      :::
+
+      :::warning
+      :::
+
+      :::tip
+      :::
+
+      :::info
+      :::
+
+      :::note
+      :::
+      "
+    `);
+  });
+
+  it("should allow customizing the default mapping", async () => {
+    const mapping: AlertTypeMapping = {
+      ...DEFAULT_MAPPING,
+      [GithubAlertType.IMPORTANT]: DirectiveName.WARNING,
+    };
+
+    const input = `
+> [!IMPORTANT]
+> content
+`;
+
+    const file = await remark()
+      .use(remarkGithubAdmonitionsToDirectives, { mapping })
+      .use(remarkDirective)
+      .process(input);
+
+    const result = file.toString();
+
+    expect(result).toMatchInlineSnapshot(`
+      ":::warning
+      content
+      :::
+      "
+    `);
+  });
 });

src/plugin.ts

@@ -2,10 +2,16 @@ import type { Blockquote, Parent, Root } from "mdast";
 import type { ContainerDirective } from "mdast-util-directive";
 import type { Plugin } from "unified";
 import { visit } from "unist-util-visit";
-import { mapGithubAlertTypeToDirectiveName } from "./map-github-alert-type-to-directive-name.js";
+import { DEFAULT_MAPPING } from "./default-mapping.const.js";
+import type { Options } from "./options.type.js";
 import { parseGithubAlertBlockquote } from "./parse-github-alert-blockquote.js";
 
-export const remarkGithubAdmonitionsToDirectives: Plugin<[], Root> = () => {
+export const remarkGithubAdmonitionsToDirectives: Plugin<
+  [options?: Options],
+  Root
+> = (options) => {
+  const { mapping = DEFAULT_MAPPING } = options ?? {};
+
   return (tree) => {
     visit(
       tree,
@@ -17,7 +23,7 @@ export const remarkGithubAdmonitionsToDirectives: Plugin<[], Root> = () => {
 
         const directive: ContainerDirective = {
           type: "containerDirective",
-          name: mapGithubAlertTypeToDirectiveName(githubAlert.type),
+          name: mapping[githubAlert.type],
           children: githubAlert.children,
         };