@fsegurai/marked-extended-alert

v17.0.0

Published

a month ago

Extension for Marked.js that adds support for extended alerts, allowing the creation of visually distinct note, warning, tip, and other information boxes in your Markdown content. It supports any Markdown rendering and can be customized to fit your needs.

Downloads

118

0High
0Medium
0Low

fsegurai

extensions javascript library markdown markedjs marked-extended-alert parser syntax typescript

An extension library for Marked.js to enhance Markdown rendering.

@fsegurai/marked-extended-alert Extension for Marked.js that adds support for extended alerts, allowing the creation of visually distinct note, warning, tip, and other information boxes in your Markdown content. It supports any Markdown rendering and can be customized to fit your needs. It supports any Markdown rendering and can be customized to fit your needs.

🎯 Overview

The marked-extended-alert extension brings GitHub Flavored Markdown (GFM) alerts to your Marked.js projects. Create visually distinct, accessible callout boxes that highlight important information with automatic icons, color coding, and semantic HTML structure.

✨ Key Features

🎨 GitHub-Style Alerts: 5 built-in alert types matching GitHub's design
🎭 Auto Icons: SVG icons automatically included for each alert type
🎨 Customizable: Override icons, titles, and styling to match your brand
♿ Accessible: Semantic HTML with proper ARIA attributes
🔄 Nested Content: Full Markdown support within alerts (lists, code, tables)
📦 Framework Agnostic: Works with React, Vue, Angular, Svelte, and vanilla JS
🌗 Theme Support: Light and dark mode styling included
⚡ Lightweight: Minimal overhead with native blockquote transformation

🎪 Live Demo

Experience all alert types in action: View Demo

Installation

To add @fsegurai/marked-extended-alert along with Marked.js to your package.json use the following commands.

bun install @fsegurai/marked-extended-alert marked@^17 --save

Usage

Basic Usage

Import @fsegurai/marked-extended-alert and apply it to your Marked instance as shown below.

Quick Start

Basic Syntax

Alerts use GitHub-style syntax with > [!TYPE] markers. This extension transforms standard Markdown blockquotes into styled alert boxes:

> [!NOTE]
> Important information users should know.

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

> [!IMPORTANT]
> Critical information for success.

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

> [!CAUTION]
> Danger or critical warnings.

import { marked } from 'marked';
import markedExtendedAlert from '@fsegurai/marked-extended-alert';

// or UMD script
// <script src="https://cdn.jsdelivr.net/npm/marked/lib/marked.umd.js"></script>
// <script src="https://cdn.jsdelivr.net/npm/@fsegurai/marked-extended-alert/lib/index.umd.js"></script>

marked.use(markedExtendedAlert());

### Installation

Install the package using your preferred package manager:

```bash
# Using Bun (recommended)
bun add @fsegurai/marked-extended-alert

# Using npm
npm install @fsegurai/marked-extended-alert

# Using yarn
yarn add @fsegurai/marked-extended-alert

# Using pnpm
pnpm add @fsegurai/marked-extended-alert

Basic Implementation

import { marked } from 'marked';
import markedExtendedAlert from '@fsegurai/marked-extended-alert';

// Import styles (required for functionality)
import '@fsegurai/marked-extended-alert/styles/alert.css';
// Optional: Import theme for styled appearance
import '@fsegurai/marked-extended-alert/styles/alert-theme.css';

// Register the extension
marked.use(markedExtendedAlert());

// Your markdown content
const markdown = `
> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
`;

// Parse and render
const html = marked.parse(markdown);
console.log(html);

Syntax & Usage

Alerts are created using GitHub Flavored Markdown syntax. Start a blockquote with > [!TYPE] where TYPE is one of the supported alert types:

> [!NOTE]
> Your content here...

Multiple Paragraphs:

> [!TIP]
> First paragraph with helpful information.
>
> Second paragraph with more details.
>
> - Bullet point 1
> - Bullet point 2

Code Blocks in Alerts:

> [!IMPORTANT]
> Make sure to configure your API key:
>
> ```javascript
> const API_KEY = process.env.API_KEY;
> ```

Tables in Alerts:

> [!WARNING]
> Rate limits vary by plan:
>
> | Plan | Requests/hour |
> |------|---------------|
> | Free | 100 |
> | Pro  | 1000 |

Links and Formatting:

> [!NOTE]
> See the [official documentation](https://example.com) for more details.
> You can use **bold**, *italic*, and `code` formatting.


### Content Support

The extension supports **full Markdown syntax** within alerts, including:

- ✅ **Paragraphs and text formatting** (bold, italic, strikethrough)
- ✅ **Lists** (ordered, unordered, task lists)
- ✅ **Code blocks** (with syntax highlighting)
- ✅ **Tables** (all table features)
- ✅ **Links and images**
- ✅ **Nested blockquotes**
- ✅ **Inline code and HTML**

All alerts are rendered with **semantic HTML** and include proper **accessibility attributes** for screen readers.

### Importing Styles

Starting from version 17.0.0, this extension **does not automatically inject styles**. You must import the CSS or SCSS files manually to ensure proper styling.

#### Option 1: Using CSS (Recommended for most projects)

```javascript
// Import minimal structural styles (required for functionality)
import '@fsegurai/marked-extended-alert/styles/alert.css';

// Optional: Import the GitHub-style theme
import '@fsegurai/marked-extended-alert/styles/alert-theme.css';

Or in your HTML:

<link rel="stylesheet" href="node_modules/@fsegurai/marked-extended-alert/styles/alert.css">
<link rel="stylesheet" href="node_modules/@fsegurai/marked-extended-alert/styles/alert-theme.css">

Or using CDN:

<!-- Latest version -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fsegurai/marked-extended-alert@latest/styles/alert.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fsegurai/marked-extended-alert@latest/styles/alert-theme.css">

<!-- Or lock to a specific version (recommended for production) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fsegurai/[email protected]/styles/alert.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fsegurai/[email protected]/styles/alert-theme.css">

Option 2: Using SCSS (For customization)

// Import structural styles with customizable variables
@import '@fsegurai/marked-extended-alert/styles/alert.scss';

// Optional: Import theme with customizable variables
@import '@fsegurai/marked-extended-alert/styles/alert-theme.scss';

// Customize SCSS variables before importing (optional)
$alert-padding: 1rem 1.5rem;
$alert-border-width: 4px;
@import '@fsegurai/marked-extended-alert/styles/alert-theme.scss';

Available Style Files

| File | Purpose | Required | |----------------------------|------------------------------------------|-----------------------| | styles/alert.css | Minimal structural CSS for functionality | ✅ Yes | | styles/alert.scss | SCSS version with customizable variables | ✅ Yes (if using SCSS) | | styles/alert-theme.css | GitHub-style theme with light/dark mode | ❌ Optional | | styles/alert-theme.scss | SCSS theme with customizable variables | ❌ Optional |

Angular Integration

For Angular projects using ngx-markdown:

// In your angular.json, add the CSS files to styles array:
{
  "styles": [
    "node_modules/@fsegurai/marked-extended-alert/styles/alert.css",
    "node_modules/@fsegurai/marked-extended-alert/styles/alert-theme.css"
  ]
}

// Or import in your global styles.scss:
@import '@fsegurai/marked-extended-alert/styles/alert.scss';
@import '@fsegurai/marked-extended-alert/styles/alert-theme.scss';

Vanilla HTML/JavaScript Example

Complete example for projects without build tools:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Marked Extended Alert Example</title>
  
  <!-- Import Marked.js from CDN -->
  <script src="https://cdn.jsdelivr.net/npm/marked@17/lib/marked.umd.js"></script>
  
  <!-- Import Alert Extension from CDN -->
  <script src="https://cdn.jsdelivr.net/npm/@fsegurai/marked-extended-alert@latest/dist/index.umd.js"></script>
  
  <!-- Import Alert Styles from CDN -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fsegurai/marked-extended-alert@latest/styles/alert.css">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fsegurai/marked-extended-alert@latest/styles/alert-theme.css">
</head>
<body>
  <div id="content"></div>

  <script>
    // Configure marked with the alert extension
    marked.use(markedExtendedAlert());

    // Your markdown content
    const markdown = `
> [!NOTE]
> This is a note alert with useful information.

> [!WARNING]
> This is a warning that requires attention.
    `;

    // Render the markdown
    document.getElementById('content').innerHTML = marked.parse(markdown);
  </script>
</body>
</html>

Migration from v16 to v17

If you're upgrading from v16:

// v16 (old - no longer supported)
marked.use(markedExtendedAlert({ injectStyles: true }));

// v17 (new approach)
import '@fsegurai/marked-extended-alert/styles/alert.css';
marked.use(markedExtendedAlert());

Note: The injectStyles option has been completely removed in v17.0.0.

Styling Your Alerts

This extension follows a separation of concerns approach, injecting only minimal structural CSS required for alert functionality (layout, positioning, display). Visual styling is completely separated, giving you maximum flexibility to match your design system.

Generated HTML Structure

The extension generates the following semantic HTML structure:

<div class="marked-extended-alert marked-extended-alert-note">
  <p class="marked-extended-alert-title">
    <svg class="octicon octicon-info mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
      <!-- SVG path data -->
    </svg>
    Note
  </p>
  <div class="marked-extended-alert-content">
    <p>Your alert content rendered here...</p>
    <!-- Additional content elements -->
  </div>
</div>

Benefits of this structure:

✅ Semantic HTML for better accessibility
✅ Proper heading hierarchy with <p> tag for title
✅ SVG icons for crisp display at any size
✅ Content wrapper for consistent styling
✅ Type-specific classes for easy customization

CSS Classes Reference

| Class | Element | Purpose | |----------------------------------|---------|------------------------------------------| | .marked-extended-alert | div | Base container for all alerts | | .marked-extended-alert-note | div | Note-specific styling (blue theme) | | .marked-extended-alert-tip | div | Tip-specific styling (green theme) | | .marked-extended-alert-important | div | Important-specific styling (purple theme) | | .marked-extended-alert-warning | div | Warning-specific styling (orange theme) | | .marked-extended-alert-caution | div | Caution-specific styling (red theme) | | .marked-extended-alert-title | p | Title container with icon | | .marked-extended-alert-content | div | Content wrapper |

Styling Targets:

Container: Border, margin, padding, background, border-radius
Title: Font weight, color, icon spacing, flex layout
Content: Padding, line height, text color
Icons: Size, color, margins

Styling Methods

Method 1: Use the Included Theme (Quickest)

The extension provides a complete GitHub-style theme:

import '@fsegurai/marked-extended-alert/styles/alert.css';
import '@fsegurai/marked-extended-alert/styles/alert-theme.css';

This includes:

✅ All 5 alert types with proper colors
✅ Light and dark mode support
✅ Responsive design
✅ Icon styling
✅ GitHub-accurate colors

Method 2: Custom CSS (Full Control)

Create your own styles targeting the classes:

/* Base alert styling */
.marked-extended-alert {
  padding: 1rem 1.5rem;
  margin: 1rem 0;
  border-left: 4px solid;
  border-radius: 4px;
  background: #f8f9fa;
}

.marked-extended-alert-title {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-weight: 600;
  margin: 0 0 0.75rem 0;
  font-size: 1rem;
}

.marked-extended-alert-title svg {
  width: 1.25rem;
  height: 1.25rem;
  flex-shrink: 0;
}

.marked-extended-alert-content {
  line-height: 1.6;
}

.marked-extended-alert-content > *:first-child {
  margin-top: 0;
}

.marked-extended-alert-content > *:last-child {
  margin-bottom: 0;
}

/* Note - Blue Theme */
.marked-extended-alert-note {
  border-left-color: #0969da;
  background: rgba(9, 105, 218, 0.1);
}

.marked-extended-alert-note .marked-extended-alert-title {
  color: #0969da;
}

.marked-extended-alert-note .marked-extended-alert-title svg {
  fill: #0969da;
}

/* Tip - Green Theme */
.marked-extended-alert-tip {
  border-left-color: #1a7f37;
  background: rgba(26, 127, 55, 0.1);
}

.marked-extended-alert-tip .marked-extended-alert-title {
  color: #1a7f37;
}

.marked-extended-alert-tip .marked-extended-alert-title svg {
  fill: #1a7f37;
}

/* Important - Purple Theme */
.marked-extended-alert-important {
  border-left-color: #8250df;
  background: rgba(130, 80, 223, 0.1);
}

.marked-extended-alert-important .marked-extended-alert-title {
  color: #8250df;
}

.marked-extended-alert-important .marked-extended-alert-title svg {
  fill: #8250df;
}

/* Warning - Orange Theme */
.marked-extended-alert-warning {
  border-left-color: #9a6700;
  background: rgba(154, 103, 0, 0.1);
}

.marked-extended-alert-warning .marked-extended-alert-title {
  color: #9a6700;
}

.marked-extended-alert-warning .marked-extended-alert-title svg {
  fill: #9a6700;
}

/* Caution - Red Theme */
.marked-extended-alert-caution {
  border-left-color: #cf222e;
  background: rgba(207, 34, 46, 0.1);
}

.marked-extended-alert-caution .marked-extended-alert-title {
  color: #cf222e;
}

.marked-extended-alert-caution .marked-extended-alert-title svg {
  fill: #cf222e;
}

Method 3: CSS Variables (Theme-Aware)

Use CSS variables for easy theming and customization:

:root {
  /* Base alert variables */
  --alert-padding: 1rem 1.5rem;
  --alert-margin: 1rem 0;
  --alert-border-width: 4px;
  --alert-border-radius: 4px;
  
  /* Alert type colors */
  --alert-note-color: #0969da;
  --alert-tip-color: #1a7f37;
  --alert-important-color: #8250df;
  --alert-warning-color: #9a6700;
  --alert-caution-color: #cf222e;
  
  /* Background opacity */
  --alert-bg-opacity: 0.1;
}

.marked-extended-alert {
  padding: var(--alert-padding);
  margin: var(--alert-margin);
  border-left: var(--alert-border-width) solid;
  border-radius: var(--alert-border-radius);
}

.marked-extended-alert-note {
  border-left-color: var(--alert-note-color);
  background: rgba(9, 105, 218, var(--alert-bg-opacity));
}

.marked-extended-alert-note .marked-extended-alert-title {
  color: var(--alert-note-color);
}

/* Repeat for other alert types... */

.marked-extended-alert-note .marked-extended-alert-title { color: #0969da; }

.marked-extended-alert-tip { border-left-color: #1a7f37; background: rgba(26, 127, 55, 0.1); }

.marked-extended-alert-tip .marked-extended-alert-title { color: #1a7f37; }

.marked-extended-alert-important { border-left-color: #8250df; background: rgba(130, 80, 223, 0.1); }

.marked-extended-alert-important .marked-extended-alert-title { color: #8250df; }

.marked-extended-alert-warning { border-left-color: #9a6700; background: rgba(154, 103, 0, 0.1); }

.marked-extended-alert-warning .marked-extended-alert-title { color: #9a6700; }

.marked-extended-alert-caution { border-left-color: #cf222e; background: rgba(207, 34, 46, 0.1); }

.marked-extended-alert-caution .marked-extended-alert-title { color: #cf222e; }


#### Dark Mode Support

Add dark theme overrides for better accessibility:

```css
/* Light theme (default) */
.marked-extended-alert {
  color: #24292e;
  background: #f8f9fa;
}

/* Dark theme */
@media (prefers-color-scheme: dark) {
  .marked-extended-alert {
    color: #d1d5da;
    background: rgba(255, 255, 255, 0.05);
  }
  
  .marked-extended-alert-note {
    border-left-color: #539bf5;
  }
  
  .marked-extended-alert-note .marked-extended-alert-title {
    color: #539bf5;
  }
  
  .marked-extended-alert-tip {
    border-left-color: #57ab5a;
  }
  
  .marked-extended-alert-tip .marked-extended-alert-title {
    color: #57ab5a;
  }
  
  .marked-extended-alert-important {
    border-left-color: #986ee2;
  }
  
  .marked-extended-alert-important .marked-extended-alert-title {
    color: #986ee2;
  }
  
  .marked-extended-alert-warning {
    border-left-color: #c69026;
  }
  
  .marked-extended-alert-warning .marked-extended-alert-title {
    color: #c69026;
  }
  
  .marked-extended-alert-caution {
    border-left-color: #e5534b;
  }
  
  .marked-extended-alert-caution .marked-extended-alert-title {
    color: #e5534b;
  }
}

/* Manual theme toggle (if not using prefers-color-scheme) */
body.dark .marked-extended-alert {
  color: #d1d5da;
  background: rgba(255, 255, 255, 0.05);
}

body.dark .marked-extended-alert-note {
  border-left-color: #539bf5;
}

/* ... repeat for other types */

Accessibility Enhancements

Ensure alerts are accessible to all users:

/* Focus styles for keyboard navigation */
.marked-extended-alert:focus-within {
  outline: 2px solid currentColor;
  outline-offset: 2px;
}

/* High contrast mode support */
@media (prefers-contrast: high) {
  .marked-extended-alert {
    border: 2px solid;
    border-left-width: 4px;
  }
}

/* Reduced motion support */
@media (prefers-reduced-motion: reduce) {
  .marked-extended-alert * {
    animation: none !important;
    transition: none !important;
  }
}

/* Ensure sufficient color contrast */
.marked-extended-alert-content {
  color: inherit;
  contrast: 4.5:1; /* WCAG AA compliant */
}

Icon Customization

Icons are inline SVG elements. You can customize them in multiple ways:

Option 1: Replace with Emoji via CSS

/* Hide default SVG icons */
.marked-extended-alert-title svg {
  display: none;
}

/* Add emoji icons */
.marked-extended-alert-note .marked-extended-alert-title::before {
  content: "ℹ️ ";
}

.marked-extended-alert-tip .marked-extended-alert-title::before {
  content: "💡 ";
}

.marked-extended-alert-important .marked-extended-alert-title::before {
  content: "❗ ";
}

.marked-extended-alert-warning .marked-extended-alert-title::before {
  content: "⚠️ ";
}

.marked-extended-alert-caution .marked-extended-alert-title::before {
  content: "🛑 ";
}

Option 2: Customize SVG Colors

/* Change icon colors independently */
.marked-extended-alert-note .marked-extended-alert-title svg {
  fill: #0066cc; /* Custom blue */
}

.marked-extended-alert-tip .marked-extended-alert-title svg {
  fill: #28a745; /* Custom green */
}

/* Change icon size */
.marked-extended-alert-title svg {
  width: 1.5rem;
  height: 1.5rem;
}

Option 3: Replace with Custom SVGs via JavaScript

import markedExtendedAlert from '@fsegurai/marked-extended-alert';

marked.use(markedExtendedAlert({
  variants: [
    {
      type: 'note',
      icon: '<svg viewBox="0 0 24 24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"/></svg>',
      title: 'Note'
    },
    {
      type: 'tip',
      icon: '💡', // Or use emoji directly
      title: 'Pro Tip'
    }
  ]
}));

Option 4: Use Font Icons (Font Awesome, etc.)

marked.use(markedExtendedAlert({
  variants: [
    {
      type: 'note',
      icon: '<i class="fas fa-info-circle"></i>',
      title: 'Note'
    },
    {
      type: 'tip',
      icon: '<i class="fas fa-lightbulb"></i>',
      title: 'Tip'
    }
  ]
}));

Alert Types

The extension supports 5 alert types with automatic icons and color coding, following GitHub's design:

| Type | Syntax | Icon | Color | Usage | |-------------|----------------|------|--------|----------------------------------------------------------| | NOTE | > [!NOTE] | ℹ️ | Blue | General information, context, or neutral explanations | | TIP | > [!TIP] | 💡 | Green | Helpful suggestions, best practices, or optimization tips| | IMPORTANT| > [!IMPORTANT]| 📌 | Purple | Critical information that affects core functionality | | WARNING | > [!WARNING] | ⚠️ | Orange | Important warnings about potential issues or pitfalls | | CAUTION | > [!CAUTION] | 🛑 | Red | Danger alerts about risks, data loss, or critical errors |

When to Use Each Type

NOTE (ℹ️ Blue) - Informational context

> [!NOTE]
> This API endpoint returns paginated results with a maximum of 100 items per page.

✅ Use for: Additional context, background information, explanations
❌ Avoid for: Critical warnings or action items

TIP (💡 Green) - Helpful advice

> [!TIP]
> Use caching to reduce API calls and improve performance.

✅ Use for: Optimization tips, best practices, shortcuts, recommendations
❌ Avoid for: Required information or critical instructions

IMPORTANT (📌 Purple) - Key information

> [!IMPORTANT]
> Authentication tokens expire after 24 hours and must be refreshed.

✅ Use for: Must-know information, breaking changes, key concepts
❌ Avoid for: Nice-to-know details or extreme dangers

WARNING (⚠️ Orange) - Potential problems

> [!WARNING]
> Exceeding rate limits will result in temporary API access suspension.

✅ Use for: Potential issues, deprecated features, performance impacts
❌ Avoid for: Extreme dangers or irreversible actions

CAUTION (🛑 Red) - Critical risks

> [!CAUTION]
> This operation permanently deletes all user data and cannot be undone.

✅ Use for: Data loss risks, security vulnerabilities, irreversible actions
❌ Avoid for: General warnings or informational notes

Quick Reference

> [!NOTE]
> Informational message

> [!TIP]
> Helpful suggestion

> [!IMPORTANT]
> Critical information

> [!WARNING]
> Potential problem

> [!CAUTION]
> Serious danger

Aliases

Alert types can be written in different ways for flexibility. The extension recognizes multiple keywords for each type:

Currently Supported:

NOTE: [!NOTE], [!INFO], [!INFORMATION]
TIP: [!TIP], [!HINT], [!SUGGESTION]
IMPORTANT: [!IMPORTANT], [!CRITICAL], [!KEY]
WARNING: [!WARNING], [!WARN], [!ATTENTION]
CAUTION: [!CAUTION], [!DANGER], [!ERROR], [!STOP]

Note: The default implementation uses the 5 standard GitHub alert types. Aliases would require custom variant configuration.

Example using standard types:

> [!NOTE]
> This is a note (blue).

> [!TIP]
> This is a tip (green).

> [!IMPORTANT]
> This is important (purple).

> [!WARNING]
> This is a warning (orange).

> [!CAUTION]
> This is a caution (red).

Configuration Options

The alert extension accepts configuration options when initializing. Pass them as an object to customize behavior:

marked.use(markedExtendedAlert({
  className: 'my-alert',
  variants: [...]
}));

Extension Options

| Option | Type | Default | Description | |-------------|-----------------|---------------------------|-------------------------------------------------------| | className | string | 'marked-extended-alert' | Base CSS class name applied to all alert containers | | variants | AlertVariant[]| [] | Custom variants to override or extend defaults |

AlertVariant Configuration

Each variant object supports the following properties:

| Property | Type | Required | Description | |-----------------|----------|----------|----------------------------------------------------| | type | string | ✅ Yes | Alert type identifier (e.g., 'note', 'tip') | | icon | string | ✅ Yes | HTML/SVG markup or emoji for the alert icon | | title | string | ❌ No | Display title (defaults to capitalized type) | | titleClassName| string | ❌ No | CSS class for title element |

Configuration Examples

Custom Class Name:

marked.use(markedExtendedAlert({
  className: 'custom-alert'
}));
// Generates: <div class="custom-alert custom-alert-note">

Custom Icons (Emoji):

marked.use(markedExtendedAlert({
  variants: [
    {
      type: 'note',
      icon: '📝',
      title: 'Note'
    },
    {
      type: 'tip',
      icon: '✨',
      title: 'Pro Tip'
    }
  ]
}));

Custom Icons (SVG):

marked.use(markedExtendedAlert({
  variants: [
    {
      type: 'note',
      icon: '<svg viewBox="0 0 24 24"><path d="M12 2C6.48..." fill="currentColor"/></svg>',
      title: 'Note'
    }
  ]
}));

Add New Alert Type:

marked.use(markedExtendedAlert({
  variants: [
    // Keep default types by not overriding them
    {
      type: 'success',
      icon: '✅',
      title: 'Success'
    },
    {
      type: 'info',
      icon: '💬',
      title: 'Info'
    }
  ]
}));

// Usage:
// > [!SUCCESS]
// > Operation completed successfully!

Override Default Variant:

marked.use(markedExtendedAlert({
  variants: [
    {
      type: 'note',  // Override the default 'note' variant
      icon: '📌',
      title: 'Important Note',
      titleClassName: 'custom-title-class'
    }
  ]
}));

Custom Title Classes:

marked.use(markedExtendedAlert({
  variants: [
    {
      type: 'note',
      icon: 'ℹ️',
      title: 'Note',
      titleClassName: 'alert-title-large'
    }
  ]
}));

Note: For styling, you must manually import CSS/SCSS files (see Importing Styles section).

Advanced Examples

Documentation Alerts

> [!NOTE] API Version
> This documentation covers API v2.1. For v1.x documentation, see the [legacy docs](/v1).

> [!TIP] Performance Optimization
> For better performance, consider implementing request caching:
>
> \`\`\`javascript
> const cache = new Map();
> const cachedResponse = cache.get(requestKey);
> if (cachedResponse) return cachedResponse;
> \`\`\`

> [!IMPORTANT] Breaking Changes
> Version 3.0 introduces breaking changes:
>
> - Authentication method changed from API keys to OAuth 2.0
> - Response format updated to JSON:API specification
> - Rate limiting reduced from 1000 to 500 requests per hour

> [!WARNING] Rate Limiting
> This endpoint has strict rate limits:
>
> | Tier | Requests/hour | Burst |
> |------|---------------|-------|
> | Free | 100 | 10 |
> | Pro | 1,000 | 50 |
> | Enterprise | 10,000 | 200 |
>
> Exceeding limits results in HTTP 429 responses.

> [!CAUTION] Data Loss Risk
> The following operations are **irreversible**:
>
> - `DELETE /users/{id}` - Permanently removes user and all associated data
> - `POST /reset-database` - Clears all data from the database
> - `PUT /settings/factory-reset` - Restores all settings to defaults
>
> Always create backups before performing these operations!

Tutorial Alerts

# Getting Started Tutorial

> [!TIP] Prerequisites
> Before starting, make sure you have:
> - Node.js 18+ installed
> - A GitHub account
> - Basic knowledge of JavaScript

## Step 1: Installation

> [!NOTE]
> We'll use bun for this tutorial, but you can also use yarn or pnpm, etc.

Install the required packages:

\`\`\`bash
bun install express helmet cors
\`\`\`

> [!WARNING] Security Notice
> Never commit your `.env` file containing sensitive data like API keys or database passwords to version control.

## Step 2: Configuration

> [!IMPORTANT] Environment Variables
> Create a `.env` file in your project root:
> 
> \`\`\`env
> PORT=3000
> DATABASE_URL=your_database_url
> JWT_SECRET=your_jwt_secret
> \`\`\`

> [!CAUTION] Production Deployment
> In production, ensure you:
> 1. Use HTTPS only
> 2. Set secure session cookies
> 3. Implement proper CORS policies
> 4. Use environment-specific configurations

Customization

Custom Styling Example

Create your own unique alert design:

/* Rounded, bordered style */
.marked-extended-alert {
  border: 2px solid;
  border-radius: 12px;
  padding: 1.25rem 1.5rem;
  margin: 1.5rem 0;
  background: white;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

.marked-extended-alert-title {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  font-weight: 700;
  font-size: 1.1rem;
  margin-bottom: 0.75rem;
}

/* Vibrant modern colors */
.marked-extended-alert-note {
  border-color: #3b82f6;
  background: linear-gradient(135deg, #eff6ff 0%, #dbeafe 100%);
}

.marked-extended-alert-tip {
  border-color: #10b981;
  background: linear-gradient(135deg, #f0fdf4 0%, #d1fae5 100%);
}

.marked-extended-alert-important {
  border-color: #8b5cf6;
  background: linear-gradient(135deg, #faf5ff 0%, #ede9fe 100%);
}

.marked-extended-alert-warning {
  border-color: #f59e0b;
  background: linear-gradient(135deg, #fffbeb 0%, #fed7aa 100%);
}

.marked-extended-alert-caution {
  border-color: #ef4444;
  background: linear-gradient(135deg, #fef2f2 0%, #fecaca 100%);
}

Custom Variant Configuration

import { marked } from 'marked';
import markedExtendedAlert from '@fsegurai/marked-extended-alert';

// Add custom alert types
marked.use(markedExtendedAlert({
  variants: [
    // Custom success alert
    {
      type: 'success',
      icon: '<svg viewBox="0 0 16 16" width="16" height="16"><path d="M13.78 4.22a.75.75 0 010 1.06l-7.25 7.25a.75.75 0 01-1.06 0L2.22 9.28a.75.75 0 011.06-1.06L6 10.94l6.72-6.72a.75.75 0 011.06 0z"></path></svg>',
      title: 'Success'
    },
    // Custom question alert
    {
      type: 'question',
      icon: '❓',
      title: 'Question'
    },
    // Custom bug alert
    {
      type: 'bug',
      icon: '🐛',
      title: 'Known Bug'
    }
  ]
}));

// Usage:
// > [!SUCCESS]
// > Your changes have been saved successfully.
//
// > [!QUESTION]
// > Need help? Contact support at [email protected]
//
// > [!BUG]
// > This feature currently has issues on Safari browsers.

Best Practices

1. Choose the Right Alert Type

Match the alert type to the severity and purpose:

<!-- Good: Appropriate severity levels -->
> [!NOTE]
> API version 2.0 is now available.

> [!WARNING]
> This method will be deprecated in version 3.0.

> [!CAUTION]
> Never commit API keys to version control.

<!-- Avoid: Wrong severity levels -->
> [!CAUTION]
> We updated our logo.  <!-- ❌ Too severe -->

> [!NOTE]
> Your account will be deleted!  <!-- ❌ Too mild -->

2. Keep Content Concise

Alerts should be scannable and to-the-point:

<!-- Good: Concise and clear -->
> [!TIP]
> Use `Promise.all()` to run multiple async operations in parallel.

<!-- Avoid: Too verbose -->
> [!TIP]
> If you have multiple asynchronous operations that need to be executed...
> (50 more lines of explanation)

3. Use Consistent Formatting

Maintain consistent styling across your documentation:

<!-- Good: Consistent structure -->
> [!NOTE] Prerequisites
> Node.js 18+ and npm required.

> [!NOTE] Installation
> Run `npm install` to get started.

<!-- Avoid: Inconsistent -->
> [!NOTE]
> Node.js 18+ and npm required.

> [!TIP] Installation
> Run `npm install` to get started.

4. Don't Overuse Alerts

Too many alerts reduce their effectiveness:

<!-- Good: Strategic alert usage -->
# Installation Guide

Follow these steps to install...

> [!WARNING]
> Requires administrator privileges on Windows.

## Step 1: Download...

<!-- Avoid: Alert fatigue -->
# Installation Guide

> [!NOTE]
> This is a guide.

> [!TIP]
> Read carefully.

> [!IMPORTANT]
> Pay attention.

> [!WARNING]
> Don't skip steps.

5. Combine with Other Markdown

Alerts work with all Markdown features:

> [!TIP] Performance Optimization
> For better performance:
>
> 1. Enable caching
> 2. Minimize API calls
> 3. Use batch operations
>
> See [Performance Guide](/docs/performance) for details.

6. Accessibility Considerations

Use semantic alert types (don't use CAUTION for tips)
Ensure color contrast meets WCAG AA standards
Provide text alternatives for icon meanings
Test with screen readers

7. Mobile Responsiveness

/* Adjust alert padding on mobile */
@media (max-width: 768px) {
  .marked-extended-alert {
    padding: 0.875rem 1rem;
    margin: 1rem 0;
  }
  
  .marked-extended-alert-title {
    font-size: 0.95rem;
  }
}

Performance Tips

Minimal CSS: Import only required styles

// Import only base styles if using custom theme
import '@fsegurai/marked-extended-alert/styles/alert.css';

CSS Containment: Improve rendering performance

.marked-extended-alert {
  contain: layout style paint;
}

Reduce Complexity: Avoid overly complex nested content

<!-- Good: Simple, fast rendering -->
> [!NOTE]
> Quick note with [a link](https://example.com).

<!-- Avoid: Complex, slower rendering -->
> [!NOTE]
> Complex note with tables, images, nested lists...
> (100+ lines of complex content)

Lazy Loading: For pages with many alerts

// Intersection Observer for lazy content loading
const alerts = document.querySelectorAll('.marked-extended-alert');
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      entry.target.classList.add('loaded');
    }
  });
});

alerts.forEach(alert => observer.observe(alert));

Troubleshooting

Alerts Not Showing

Problem: Blockquotes remain as regular quotes.

Solutions:

Verify the syntax: > [!TYPE] with uppercase type

<!-- Correct -->
> [!NOTE]
> Content

<!-- Wrong -->
> [!note]  <!-- ❌ Lowercase -->
> Content

> [! NOTE]  <!-- ❌ Space after ! -->
> Content

Ensure the extension is registered:

import markedExtendedAlert from '@fsegurai/marked-extended-alert';
marked.use(markedExtendedAlert());  // ✅ Don't forget this!

Check if the alert type is supported or custom:

// For custom types, configure variants
marked.use(markedExtendedAlert({
  variants: [{ type: 'custom', icon: '🎨', title: 'Custom' }]
}));

Styling Not Applied

Problem: Alerts appear unstyled.

Solutions:

Import CSS files:

import '@fsegurai/marked-extended-alert/styles/alert.css';
import '@fsegurai/marked-extended-alert/styles/alert-theme.css';

Check CSS file paths in your build configuration
Verify CSS specificity (use browser DevTools)
For CDN usage, check network tab for 404 errors

Icons Not Displaying

Problem: Icons are missing or broken.

Solutions:

Check SVG icon markup is valid
Ensure SVG viewBox is set correctly
Verify fill/stroke colors are applied

.marked-extended-alert-title svg {
  fill: currentColor; /* Inherit text color */
}

Content Overflow

Problem: Long content breaks layout.

Solution:

.marked-extended-alert-content {
  overflow-wrap: break-word;
  word-wrap: break-word;
}

.marked-extended-alert-content pre {
  overflow-x: auto;
  max-width: 100%;
}

Custom Variants Not Working

Problem: Custom alert types don't render.

Solutions:

Ensure type matches markdown exactly (case-insensitive):

// Configuration
variants: [{ type: 'custom', icon: '🎨' }]

// Markdown (case-insensitive match)
> [!CUSTOM]
> Content

Verify icon property is not empty
Check browser console for errors

Framework Integration

React Integration

// MarkdownAlert.tsx
import { marked } from 'marked';
import markedExtendedAlert from '@fsegurai/marked-extended-alert';
import '@fsegurai/marked-extended-alert/styles/alert.css';
import '@fsegurai/marked-extended-alert/styles/alert-theme.css';
import { useEffect, useState } from 'react';

// Configure marked
marked.use(markedExtendedAlert());

interface MarkdownAlertProps {
  content: string;
}

export function MarkdownAlert({ content }: MarkdownAlertProps) {
  const [html, setHtml] = useState('');
  
  useEffect(() => {
    const parsed = marked.parse(content);
    setHtml(parsed);
  }, [content]);
  
  return (
    <div 
      className="markdown-content"
      dangerouslySetInnerHTML={{ __html: html }} 
    />
  );
}

// Usage:
// <MarkdownAlert content={`> [!NOTE]\n> Your note here`} />

Vue 3 Integration

<script setup lang="ts">
import { marked } from 'marked';
import markedExtendedAlert from '@fsegurai/marked-extended-alert';
import '@fsegurai/marked-extended-alert/styles/alert.css';
import '@fsegurai/marked-extended-alert/styles/alert-theme.css';
import { ref, computed } from 'vue';

marked.use(markedExtendedAlert());

interface Props {
  content: string;
}

const props = defineProps<Props>();

const html = computed(() => marked.parse(props.content));
</script>

<template>
  <div class="markdown-content" v-html="html" />
</template>

Angular Integration

// markdown-alert.component.ts
import { Component, Input, OnChanges } from '@angular/core';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
import { marked } from 'marked';
import markedExtendedAlert from '@fsegurai/marked-extended-alert';

marked.use(markedExtendedAlert());

@Component({
  selector: 'app-markdown-alert',
  template: `<div [innerHTML]="parsedContent"></div>`,
  styleUrls: [
    '../node_modules/@fsegurai/marked-extended-alert/styles/alert.css',
    '../node_modules/@fsegurai/marked-extended-alert/styles/alert-theme.css'
  ]
})
export class MarkdownAlertComponent implements OnChanges {
  @Input() content: string = '';
  parsedContent: SafeHtml = '';

  constructor(private sanitizer: DomSanitizer) {}

  ngOnChanges(): void {
    const html = marked.parse(this.content);
    this.parsedContent = this.sanitizer.bypassSecurityTrustHtml(html);
  }
}

Svelte Integration

<script lang="ts">
  import { marked } from 'marked';
  import markedExtendedAlert from '@fsegurai/marked-extended-alert';
  import '@fsegurai/marked-extended-alert/styles/alert.css';
  import '@fsegurai/marked-extended-alert/styles/alert-theme.css';
  
  marked.use(markedExtendedAlert());
  
  export let content: string;
  
  $: html = marked.parse(content);
</script>

<div class="markdown-content">
  {@html html}
</div>

Next.js Integration

// app/components/MarkdownAlert.tsx
'use client';

import { marked } from 'marked';
import markedExtendedAlert from '@fsegurai/marked-extended-alert';
import '@fsegurai/marked-extended-alert/styles/alert.css';
import '@fsegurai/marked-extended-alert/styles/alert-theme.css';
import { useMemo } from 'react';

marked.use(markedExtendedAlert());

interface MarkdownAlertProps {
  content: string;
}

export function MarkdownAlert({ content }: MarkdownAlertProps) {
  const html = useMemo(() => marked.parse(content), [content]);
  
  return (
    <div 
      className="prose max-w-none"
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

Real-World Use Cases

1. API Documentation

# User Authentication API

## POST /auth/login

Authenticates a user and returns a JWT token.

> [!IMPORTANT] Rate Limiting
> This endpoint is rate-limited to 5 requests per minute per IP address.

> [!NOTE] Request Body
> \`\`\`json
> {
>   "email": "[email protected]",
>   "password": "your-password"
> }
> \`\`\`

> [!WARNING] Security Best Practices
> - Never log or store passwords in plain text
> - Use HTTPS in production
> - Implement CSRF protection
> - Rotate JWT secrets regularly

> [!CAUTION] Account Lockout
> After 5 failed login attempts, the account will be locked for 30 minutes.

2. Installation Guides

# Installation Guide

> [!TIP] Prerequisites Check
> Verify you have Node.js 18+ installed:
> \`\`\`bash
> node --version
> \`\`\`

## Step 1: Install Dependencies

\`\`\`bash
npm install @your-org/package
\`\`\`

> [!WARNING] Peer Dependencies
> This package requires \`marked@17\` as a peer dependency. Install it if you haven't:
> \`\`\`bash
> npm install marked@17
> \`\`\`

## Step 2: Configure

> [!IMPORTANT] Environment Variables
> Create a \`.env\` file in your project root:
> \`\`\`env
> API_KEY=your_api_key_here
> API_ENDPOINT=https://api.example.com
> \`\`\`

> [!CAUTION] Security Warning
> **Never commit \`.env\` files** to version control. Add it to \`.gitignore\`:
> \`\`\`
> .env
> .env.local
> \`\`\`

3. Tutorial Content

# React Hooks Tutorial

## useState Hook

> [!NOTE] What is useState?
> \`useState\` is a Hook that lets you add state to functional components.

> [!TIP] When to Use
> Use \`useState\` when you need to track component state that changes over time.

> [!IMPORTANT] State Updates are Async
> React batches state updates for performance. Don't rely on immediate updates.

> [!CAUTION] State Mutation
> Never mutate state directly - always create new objects or arrays.

4. Security Documentation

# Security Best Practices

> [!CAUTION] Critical Security Requirements
> Failure to follow these practices may result in data breaches or account compromise.

## Password Security

> [!WARNING] Password Requirements
> Enforce strong password requirements:
> - Minimum 12 characters
> - Mix of uppercase, lowercase, numbers, symbols
> - No common passwords or patterns

## API Security

> [!IMPORTANT] Authentication
> All API endpoints **must** require authentication except:
> - Health check endpoints
> - Public documentation
> - Login/registration endpoints

5. Migration Guides

# Migration Guide: v2 to v3

> [!IMPORTANT] Breaking Changes
> Version 3.0 introduces several breaking changes. Review this guide carefully before upgrading.

> [!CAUTION] API Key Authentication Removed
> API key authentication is **deprecated** and will stop working on December 31, 2024.
> 
> **Action Required**: Migrate to OAuth 2.0 before the deadline.

> [!TIP] Migration Steps
> 1. Create OAuth application in dashboard
> 2. Update your authentication code
> 3. Test in staging environment
> 4. Deploy to production

6. Release Notes

# Release Notes - v3.0.0

## New Features

> [!TIP] Performance Improvements
> This release includes significant performance optimizations:
> - 40% faster initial page load
> - 60% reduction in bundle size
> - Improved caching strategies

## Breaking Changes

> [!IMPORTANT] Node.js 18+ Required
> This version requires Node.js 18 or higher. Node.js 16 is no longer supported.

> [!WARNING] Deprecated Methods
> The following methods are deprecated and will be removed in v4.

Contributing

Found a bug or have a feature request? Please open an issue on GitHub.

Related Resources

Available Extensions

| Extension | Package | Version | Description | |-------------|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|----------------------------------------------------------------------| | All - Bundle | @fsegurai/marked-extended-bundle | npm | Includes all extensions in a single package for easy integration | | Accordion | @fsegurai/marked-extended-accordion | npm | Add collapsible accordion sections to your markdown | | Alert | @fsegurai/marked-extended-alert | npm | Create styled alert boxes for important information | | Comments | @fsegurai/marked-extended-comments | npm | Add comment sections with author and timestamp metadata | | Embeds | @fsegurai/marked-extended-embeds | npm | Easily embed content from various platforms (YouTube, Twitter, etc.) | | Footnote | @fsegurai/marked-extended-footnote | npm | Add footnotes with automatic numbering | | Kanban | @fsegurai/marked-extended-kanban | npm | Create kanban boards with customizable columns and cards | | Lists | @fsegurai/marked-extended-lists | npm | Enhanced list formatting options | | Slide | @fsegurai/marked-extended-slide | npm | Create slide decks directly from markdown content | | Spoiler | @fsegurai/marked-extended-spoiler | npm | Hide content behind spoiler tags | | Tables | @fsegurai/marked-extended-tables | npm | Advanced table formatting with cell spanning | | Tabs | @fsegurai/marked-extended-tabs | npm | Create tabbed content sections | | Timeline | @fsegurai/marked-extended-timeline | npm | Display content in an interactive timeline format | | Typographic | @fsegurai/marked-extended-typographic | npm | Improve typography with smart quotes, dashes, and more |

Demo Application

To see all extensions in action, check out the [DEMO].

To set up the demo locally, follow the next steps:

git clone https://github.com/fsegurai/marked-extensions.git
bun install
bun start

This will serve the application locally at http://[::1]:8000.

License

Licensed under MIT.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🎯 Overview

✨ Key Features

🎪 Live Demo

Table of contents

Installation

Usage

Basic Usage

Quick Start

Basic Syntax

Basic Implementation

Syntax & Usage

Option 2: Using SCSS (For customization)

Available Style Files

Angular Integration

Vanilla HTML/JavaScript Example

Migration from v16 to v17

Styling Your Alerts

Generated HTML Structure

CSS Classes Reference

Styling Methods

Accessibility Enhancements

Icon Customization

Alert Types

When to Use Each Type

Quick Reference

Aliases

Configuration Options

Extension Options

AlertVariant Configuration

Configuration Examples

Advanced Examples

Documentation Alerts

Tutorial Alerts

Customization

Custom Styling Example

Custom Variant Configuration

Best Practices

1. Choose the Right Alert Type

2. Keep Content Concise

3. Use Consistent Formatting

4. Don't Overuse Alerts

5. Combine with Other Markdown

6. Accessibility Considerations

7. Mobile Responsiveness

Performance Tips

Troubleshooting

Alerts Not Showing

Styling Not Applied

Icons Not Displaying

Content Overflow

Custom Variants Not Working

Framework Integration

React Integration

Vue 3 Integration

Angular Integration

Svelte Integration

Next.js Integration

Real-World Use Cases

1. API Documentation

2. Installation Guides

3. Tutorial Content

4. Security Documentation

5. Migration Guides

6. Release Notes

Contributing

Related Resources

Available Extensions

Demo Application

License