remark-github-markdown-alerts/README.md

An unifiedjs (remark) plugin to convert GitHub Markdown alerts syntax into actual UI

# remark-github-markdown-alerts

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

> **Why this package over [jaywcjlove/remark-github-blockquote-alert][alternative]?**  
> 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](https://github.com/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][unified] ecosystem** - Works with remark, rehype and seamlessly integrates with [react-markdown][react-markdown] and MDX

## Installation

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

```ts
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:

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

```ts
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`][react-markdown] and [`common-tags`][common-tags]'s `html` helper, example code in Next.js application:

```tsx
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][unified] pipeline

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

```markdown
> [!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

```markdown
> [!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:

```ts
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:

```ts
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:

```html
<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:

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

[unified]: https://github.com/unifiedjs/unified
[react-markdown]: https://github.com/remarkjs/react-markdown
[common-tags]: https://www.npmjs.com/package/common-tags
[alternative]: https://github.com/jaywcjlove/remark-github-blockquote-alert