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
• 🛡️ 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 can be easily used with react-markdown

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

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 two main sections:

🎛️ Global Configuration (defaultConfig)

Applied to all alert types unless overridden:

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

const options = {
  defaultConfig: {
    // 🎨 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

Default Configuration Options

Alert-Specific Overrides

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

Example output

<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>

License

The MIT License