@mirrordown/mdit-github-alerts

Part of Mirrordown — a suite of markdown syntax extensions for the unified and markdown-it ecosystems.

A markdown-it plugin for the github-alerts syntax extension.

Overview

The github-alerts plugin converts GitHub-style alert blockquotes (> [!NOTE], > [!WARNING], etc.) into styled <div> containers with an icon and title. Foldable alerts are rendered as <details> elements.

<div class="markdown-alert" data-alert="note">
  <p class="markdown-alert-title">Note</p>
  <p>...</p>
</div>

Syntax

Write a blockquote with a [!TYPE] marker on the first line:

> [!NOTE]
> Useful information that users should know, even if skimming.

> [!TIP]
> Helpful advice for getting things done more effectively.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Custom titles

Override the default title by adding text after the type marker:

> [!NOTE] Custom Title
> This alert uses a custom title instead of the default.

Foldable alerts

Use + to make an alert open by default, or - to make it collapsed by default:

> [!TIP]+
> This tip is open by default.

> [!WARNING]-
> This warning is collapsed by default.

Configuration

All options are passed when registering the plugin.

Disable icons

Set icons: false to suppress the SVG icon from every alert title:

> [!NOTE]
> This note has no icon.

> [!WARNING]
> This warning has no icon.

md.use(githubAlerts, { icons: false });

Override default titles

Supply a titles map to replace the default heading text for any built-in type:

> [!TIP]
> This is a pro tip.

md.use(githubAlerts, { titles: { tip: "Pro tip" } });

Add custom alert types

Register new keywords with types. The value is the canonical type name that appears in the data-alert attribute and determines which CSS variable set applies. Style the new type with your own CSS:

md.use(githubAlerts, {
  types: { release: "release", changelog: "release" },
  titles: { release: "Release notes" }
});

[data-alert="release"] {
  --markdown-alert-color: oklch(0.55 0.18 300);
}

Install

npm install @mirrordown/mdit-github-alerts

Standalone

import MarkdownIt from "markdown-it";
import { githubAlerts } from "@mirrordown/mdit-github-alerts";
import "@mirrordown/mdit-github-alerts/github-alerts.css";

const md = new MarkdownIt().use(githubAlerts);

VitePress

// .vitepress/config.ts
import { defineConfig } from "vitepress";
import { githubAlerts } from "@mirrordown/mdit-github-alerts";
import "@mirrordown/mdit-github-alerts/github-alerts.css";

export default defineConfig({
  markdown: {
    config: (md) => md.use(githubAlerts)
  }
});

Documentation

Full documentation, more examples, and configuration options: github.com/mirrordown/mirrordown (dedicated docs site coming soon).

License

MIT © Drake Costa