---
title: "remark-github-markdown-alerts"
description: "An unified ecosystem (remark) plugin to turn the GitHub's Markdown alerts syntax into actual HTML elements, super extensible and unstyled by default."
canonical_url: "https://neg4n.dev/projects/remark-github-markdown-alerts"
md_url: "https://neg4n.dev/projects/remark-github-markdown-alerts.md"
---

# remark-github-markdown-alerts

## Resources

- [GitHub](https://github.com/neg4n/remark-github-markdown-alerts)
- [npm](https://www.npmjs.com/package/remark-github-markdown-alerts)

## README

remark-github-markdown-alertsTransform GitHub-style markdown alerts into HTML using the unified ecosystemWhy 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 systemFeatures🎯 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 MDXInstallationnpm 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-alertsRendering ModesThis 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 pipelinesComponent Mode: react-markdown, MDX, and component-based systemsimport { remarkGitHubAlerts } from 'remark-github-markdown-alerts'

// Auto-detects the right mode for your setup
remark().use(remarkGitHubAlerts)🎯 Manual Mode SelectionOverride 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 LogicComponent mode is automatically triggered when:Using with react-markdownProcessing .mdx filesFile data contains { mdx: true }File data contains { allowDangerousHtml: false }HTML mode is used for:Traditional remark → rehype → HTML pipelinesStatic site generatorsServer-side rendering without componentsUsageWith remarkimport { 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 iconsUsing 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` 
   
 `

async function ServerMarkdown() {
  const markdown = `
  > [!NOTE]
  > Server-rendered alert with custom SVG icon
  `
  
  return (
     
      {markdown}
     
  )
}With unified pipelineimport { 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.ConfigurationThe 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: ' ... ',
      classNames: {
        container: 'note-container',
        icon: 'note-icon'
      }
    },
    warning: {
      tags: {
        container: 'aside',
        title: 'h4'
      }
    }
  }
}

const processor = remark().use(remarkGitHubAlerts, options)📋 Configuration ReferencePlugin OptionsPropertyTypeDefaultDescriptionRenderingmode'auto' | 'html' | 'component''auto'Rendering mode selectiondefaultConfigPartialDeep See belowGlobal configuration for all alertsalertsAlertsConfig{}Alert-specific configuration overridesDefault Configuration OptionsPropertyTypeDefaultDescriptionCSS ClassesclassNames.containerstring'markdown-alert'Main alert container classclassNames.iconstring'markdown-alert-icon'Icon element classclassNames.titlestring'markdown-alert-title'Title/header classclassNames.contentstring'markdown-alert-content'Content body classHTML Elementstags.containerHtmlElement'div'Alert wrapper elementtags.iconHtmlElement'span'Icon container elementtags.titleHtmlElement'div'Title/header elementtags.contentHtmlElement'div'Content body elementCustomizationiconElementHtmlstring''Custom icon HTML/emojiAlert-Specific OverridesPropertyTypeDescriptionalerts.notePartialDeep Override config for [!NOTE] alertsalerts.tipPartialDeep Override config for [!TIP] alertsalerts.importantPartialDeep Override config for [!IMPORTANT] alertsalerts.warningPartialDeep Override config for [!WARNING] alertsalerts.cautionPartialDeep 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 ModeHTML Mode OutputTraditional HTML structure optimized for static sites and server-side rendering: 
   
      
    Note
   
   
     Your content here 
   
 Component Mode OutputEnhanced structure optimized for react-markdown and MDX with additional metadata: 
   
      
    Note
   
   
     Your content here 
   
 LicenseThe MIT License