remark-github-markdown-alerts

Transform GitHub-style markdown alerts into HTML using the unified ecosystem

Why this package over jaywcjlove/remark-github-blockquote-alert?
First of all, the mentioned project is a great one and has been there for a while, however it's design indicates slightly different usage - it's rather for out of the box implementation of 1:1 GitHub Alerts visuals than for custom implementations.

On the other hand, the neg4n/remark-github-markdown-alerts offers maximum extensibility with granular configuration for class names, HTML elements, and custom icons. It's both ESM and CJS compatible, completely unstyled by default (no opinionated GitHub CSS), adaptable to any design system

Features

🎯 GitHub compatibility - Renders [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION] alerts
🔄 Dual rendering modes - Smart auto-detection for HTML and component-based pipelines (react-markdown, MDX)
🛡️ 100% test coverage - Comprehensive test suite
🔧 Maximum extensibility - Configure HTML elements, class names, and custom icons per alert type
🎨 Unstyled by default - No opinionated CSS, works with any design system
📦 TypeScript support - Batteries included with typed HTML tags and more
🔧 Unified ecosystem - Works with remark, rehype and seamlessly integrates with react-markdown and MDX

Installation

npm i remark-github-markdown-alerts
# or
yarn add remark-github-markdown-alerts
# or
pnpm add remark-github-markdown-alerts
# or
bun add remark-github-markdown-alerts

Rendering Modes

This plugin automatically detects your rendering environment and optimizes output accordingly:

🔄 Auto-Detection (Recommended)

The plugin automatically chooses the optimal rendering mode:

HTML Mode: Traditional remark → rehype → HTML pipelines
Component Mode: react-markdown, MDX, and component-based systems

import { remarkGitHubAlerts } from 'remark-github-markdown-alerts'

// Auto-detects the right mode for your setup
remark().use(remarkGitHubAlerts)

🎯 Manual Mode Selection

Override auto-detection when needed:

import { remarkGitHubAlerts } from 'remark-github-markdown-alerts'

// Force HTML mode (traditional pipelines)
remark().use(remarkGitHubAlerts, { mode: 'html' })

// Force component mode (react-markdown, MDX)
remark().use(remarkGitHubAlerts, { mode: 'component' })

// Auto-detection (default)
remark().use(remarkGitHubAlerts, { mode: 'auto' })

📋 Mode Detection Logic

Component mode is automatically triggered when:

Using with react-markdown
Processing .mdx files
File data contains { mdx: true }
File data contains { allowDangerousHtml: false }

HTML mode is used for:

Traditional remark → rehype → HTML pipelines
Static site generators
Server-side rendering without components

Usage

With remark

import { remark } from 'remark'
import remarkHtml from 'remark-html'
import { remarkGitHubAlerts } from 'remark-github-markdown-alerts'

const processor = remark()
  .use(remarkGitHubAlerts)
  .use(remarkHtml)

const markdown = `
> [!NOTE]
> This is a note alert with some important information.

> [!WARNING] Custom title
> This is a warning with a custom title.
`

const result = await processor.process(markdown)
console.log(result.toString())

With React Server Components and custom icons

Using react-markdown and common-tags's html helper, example code in Next.js application:

import { MarkdownAsync } from 'react-markdown'
import { html } from 'common-tags'
import { remarkGitHubAlerts } from 'remark-github-markdown-alerts'

// ⚠️ Use only in server environment (RSC)
const customIcon = html`<svg viewBox="0 0 16 16" width="16" height="16">
  <path fill="currentColor" d="M8 16A8 8 0 1 1 8 0a8 8 0 0 1 0 16zM8.93 6.588l-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>
</svg>`

async function ServerMarkdown() {
  const markdown = `
  > [!NOTE]
  > Server-rendered alert with custom SVG icon
  `
  
  return (
    <MarkdownAsync 
      remarkPlugins={[
        [remarkGitHubAlerts, {
          alerts: {
            note: {
              iconElementHtml: customIcon
            }
          }
        }]
      ]}
    >
      {markdown}
    </MarkdownAsync>
  )
}

With unified pipeline

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import { remarkGitHubAlerts } from 'remark-github-markdown-alerts'

const processor = unified()
  .use(remarkParse)
  .use(remarkGitHubAlerts)
  .use(remarkRehype, { allowDangerousHtml: true })
  .use(rehypeStringify, { allowDangerousHtml: true })

const result = await processor.process('> [!IMPORTANT]\\n> Critical information here!')

Alert Types

> [!NOTE]
> Information that users should know.

> [!TIP]
> Helpful advice for better results.

> [!IMPORTANT]  
> Key information for success.

> [!WARNING]
> Urgent information to avoid problems.

> [!CAUTION]
> Risks or negative outcomes.

Custom Titles

> [!NOTE] Custom title
> Content with custom title.

> [!WARNING] Breaking Changes
> This version has breaking changes.

Configuration

The plugin accepts an options object with the following sections:

🎛️ Global Configuration (`defaultConfig`)

Applied to all alert types unless overridden:

import { remarkGitHubAlerts } from 'remark-github-markdown-alerts'

const options = {
  defaultConfig: {
    // General options
    mode: "auto"                   // Rendering mode selection

    // 🎨 CSS Class Names
    classNames: {
      container: 'alert',          // Main wrapper class
      icon: 'alert-icon',          // Icon container class
      title: 'alert-title',        // Title/header class
      content: 'alert-content'     // Content body class
    },
    
    // 🏗️ HTML Elements
    tags: {
      container: 'section',        // Wrapper element
      icon: 'i',                   // Icon element
      title: 'h3',                 // Title element
      content: 'div'               // Content element
    },
    
    // 🔧 Custom Icon
    iconElementHtml: '🔔'          // Default icon HTML
  }
}

🎯 Alert-Specific Configuration (`alerts`)

Override settings for individual alert types:

const options = {
  // ... defaultConfig above
  alerts: {
    note: {
      iconElementHtml: '<svg viewBox="0 0 16 16">...</svg>',
      classNames: {
        container: 'note-container',
        icon: 'note-icon'
      }
    },
    warning: {
      tags: {
        container: 'aside',
        title: 'h4'
      }
    }
  }
}

const processor = remark().use(remarkGitHubAlerts, options)

📋 Configuration Reference

Plugin Options

Property	Type	Default	Description
Rendering
`mode`	`'auto' \| 'html' \| 'component'`	`'auto'`	Rendering mode selection
`defaultConfig`	`PartialDeep<AlertConfig>`	See below	Global configuration for all alerts
`alerts`	`AlertsConfig`	`{}`	Alert-specific configuration overrides

Default Configuration Options

Property	Type	Default	Description
CSS Classes
`classNames.container`	`string`	`'markdown-alert'`	Main alert container class
`classNames.icon`	`string`	`'markdown-alert-icon'`	Icon element class
`classNames.title`	`string`	`'markdown-alert-title'`	Title/header class
`classNames.content`	`string`	`'markdown-alert-content'`	Content body class
HTML Elements
`tags.container`	`HtmlElement`	`'div'`	Alert wrapper element
`tags.icon`	`HtmlElement`	`'span'`	Icon container element
`tags.title`	`HtmlElement`	`'div'`	Title/header element
`tags.content`	`HtmlElement`	`'div'`	Content body element
Customization
`iconElementHtml`	`string`	`''`	Custom icon HTML/emoji

Alert-Specific Overrides

Property	Type	Description
`alerts.note`	`PartialDeep<AlertConfig>`	Override config for `[!NOTE]` alerts
`alerts.tip`	`PartialDeep<AlertConfig>`	Override config for `[!TIP]` alerts
`alerts.important`	`PartialDeep<AlertConfig>`	Override config for `[!IMPORTANT]` alerts
`alerts.warning`	`PartialDeep<AlertConfig>`	Override config for `[!WARNING]` alerts
`alerts.caution`	`PartialDeep<AlertConfig>`	Override config for `[!CAUTION]` alerts

[!TIP] Alert-specific configurations merge with the default config, so you only need to specify the properties you want to override.

Output Differences by Mode

HTML Mode Output

Traditional HTML structure optimized for static sites and server-side rendering:

<div class="markdown-alert markdown-alert-note">
  <div class="markdown-alert-title">
    <span class="markdown-alert-icon"></span>
    Note
  </div>
  <div class="markdown-alert-content">
    <p>Your content here</p>
  </div>
</div>

Component Mode Output

Enhanced structure optimized for react-markdown and MDX with additional metadata:

<div class="markdown-alert markdown-alert-note" data-alert-type="note">
  <div class="markdown-alert-title">
    <span class="markdown-alert-icon"></span>
    Note
  </div>
  <div class="markdown-alert-content">
    <p>Your content here</p>
  </div>
</div>

License

The MIT License