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 |
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
More Projects
Explore other projects that might interest you
faviconize
🎆 Library and CLI responsible for generating favicons in all formats and providing easy way to integrate them into your application
next-api-compose
🧬 Simple, dependency free, error aware and powerful utility to compose chain of multiple middleware into one Next.js API Route.
next-api-og-image
Easy way to generate open-graph images dynamically in HTML or React using Next.js API Routes. Suitable for serverless environment.