npm - @fsegurai/marked-extended-alert - Versions diffs - 15.0.0 - Mend

@fsegurai/marked-extended-alert 15.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,199 @@
+<p align="center">
+  <img alt="Marked Extensions Logo" src="https://raw.githubusercontent.com/fsegurai/marked-extensions/main/demo/public/marked-extensions.svg">
+</p>
+<p align="center">
+  <a href="https://github.com/fsegurai/marked-extensions/actions/workflows/release-library.yml">
+      <img src="https://github.com/fsegurai/marked-extensions/actions/workflows/release-library.yml/badge.svg"
+          alt="Build Status">
+  </a>
+  <a href="https://www.npmjs.org/package/@fsegurai/marked-extended-alert">
+      <img src="https://img.shields.io/npm/v/@fsegurai/marked-extended-alert.svg"
+          alt="Latest Release">
+  </a>
+  <br>
+  <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/fsegurai/marked-extensions">
+  <img alt="Dependency status for repo" src="https://img.shields.io/librariesio/github/fsegurai/marked-extensions">
+  <a href="https://opensource.org/licenses/MIT">
+    <img alt="GitHub License" src="https://img.shields.io/github/license/fsegurai/marked-extensions">
+  </a>
+  <br>
+  <img alt="Stars" src="https://img.shields.io/github/stars/fsegurai/marked-extensions?style=square&labelColor=343b41"/>
+  <img alt="Forks" src="https://img.shields.io/github/forks/fsegurai/marked-extensions?style=square&labelColor=343b41"/>
+</p>
+**A library of extended alert blocks for Marked.js.**
+`@fsegurai/marked-extended-alert` is an extension for Marked.js that adds support for GitHub-style alert blocks, allowing you to create visually distinct note, warning, tip, and other information boxes in your Markdown content. It supports any markdown rendering within alerts and is highly customizable to fit your needs.
+### Table of contents
+- [Installation](#installation)
+- [Usage](#usage)
+    - [Basic Usage](#basic-usage)
+    - [Configuration Options](#configuration-options)
+    - [Available Alert Types](#available-alert-types)
+- [More Resources](#more-resources)
+    - [Available Extensions](#available-extensions)
+    - [Demo Application](#demo-application)
+- [License](#license)
+## Installation
+To add `@fsegurai/marked-extended-alert` along with Marked.js to your `package.json` use the following commands.
+```bash
+bun install @fsegurai/marked-extended-alert marked@^15.0.0 --save
+```
+## Usage
+### Basic Usage
+Import `@fsegurai/marked-extended-alert` and apply it to your Marked instance as shown below.
+````javascript
+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>
+// Basic usage
+marked.use(markedExtendedAlert());
+const exampleMarkdown = `
+> [!NOTE]
+> This is a note alert with a **bold text** and a [link](https://example.com).
+> - Item 1
+> - Item 2
+> [!WARNING]
+> This is a warning alert.
+> [!TIP]
+> This is a tip alert.
+> [!NOTE]
+> This alert contains a table:
+>
+> | Header 1 | Header 2 |
+> |----------|----------|
+> | Cell 1   | Cell 2   |
+> | Cell 3   | Cell 4   |
+`;
+marked.parse(exampleMarkdown);
+```javascript
+import { marked } from "marked";
+import markedExtendedAlert from "@fsegurai/marked-extended-alert";
+// Configure with custom options
+marked.use(
+  markedExtendedAlert({
+    className: 'custom-alert',
+    variants: [
+      {
+        type: 'success',
+        icon: '<svg class="custom-icon"></svg>',
+        title: 'Success!',
+      }
+    ],
+    injectStyles: true
+  })j
+);
+const customMarkdown = \`
+> [!SUCCESS]
+> This is a custom success alert with nested markdown:
+> - Item with **bold text**
+> - Another item with \`code\`
+\`;
+const result = marked.parse(customMarkdown);
+````
+### Configuration Options
+The marked-extended-alert extension accepts the following configuration options:
+- `className`: The base CSS class name for alerts. Defaults to 'markdown-alert'.
+- `variants`: Array of custom variants to override or extend the default ones. The structure should look like this:
+    ```javascript
+    {
+      type: 'success',
+      icon: '<svg class="custom-icon"></svg>',
+      title: 'Success!',
+    }
+    ```
+- `injectStyles`: Whether to automatically inject CSS styles. Defaults to true.
+### Available Alert Types
+- `NOTE`: A note alert, typically used for additional information or tips.
+```markdown
+> [!NOTE]
+> This is a note alert.
+```
+- `TIP`: A tip alert, often used for helpful hints or suggestions.
+```markdown
+> [!TIP]
+> This is a tip alert.
+```
+- `IMPORTANT`: An important alert, used for critical information that requires attention.
+```markdown
+> [!IMPORTANT]
+> This is an important alert.
+```
+- `WARNING`: A warning alert, indicating potential issues or caution.
+```markdown
+> [!WARNING]
+> This is a warning alert.
+```
+- `CAUTION`: A caution alert, similar to a warning but with a different emphasis.
+```markdown
+> [!CAUTION]
+> This is a caution alert.
+```
+### Available Extensions
+- [Marked Extended Accordion](https://www.npmjs.com/package/@fsegurai/marked-extended-accordion)
+- [Marked Extended Alert](https://www.npmjs.com/package/@fsegurai/marked-extended-alert)
+- [Marked Extended Footnote](https://www.npmjs.com/package/@fsegurai/marked-extended-footnote)
+- [Marked Extended Lists](https://www.npmjs.com/package/@fsegurai/marked-extended-lists)
+- [Marked Extended Spoiler](https://www.npmjs.com/package/@fsegurai/marked-extended-spoiler)
+- [Marked Extended Tables](https://www.npmjs.com/package/@fsegurai/marked-extended-tables)
+- [Marked Extended Tabs](https://www.npmjs.com/package/@fsegurai/marked-extended-tabs)
+- [Marked Extended Timeline](https://www.npmjs.com/package/@fsegurai/marked-extended-timeline)
+- [Marked Extended Typographic](https://www.npmjs.com/package/@fsegurai/marked-extended-typographic)
+### Demo Application
+To see all extensions in action, check out the [[DEMO]](https://fsegurai.github.io/marked-extensions).
+To set up the demo locally, follow the next steps:
+```bash
+git clone https://github.com/fsegurai/marked-extensions.git
+bun install
+bun start
+```
+This will serve the application locally at [http://[::1]:8000](http://[::1]:8000).
+## License
+Licensed under [MIT](https://opensource.org/licenses/MIT).

package/package.json ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "name": "@fsegurai/marked-extended-alert",
+  "version": "15.0.0",
+  "description": "Extended Alerts for Marked.js",
+  "main": "./dist/index.cjs",
+  "module": "./src/index.js",
+  "browser": "./dist/index.umd.js",
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "files": [
+    "lib/",
+    "src/"
+  ],
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./lib/index.cjs"
+    }
+  },
+  "keywords": [
+    "parser",
+    "markedjs",
+    "extension",
+    "marked",
+    "marked-extended-accordion",
+    "marked-extended-alert",
+    "marked-extended-footnote",
+    "marked-extended-lists",
+    "marked-extended-spoiler",
+    "marked-extended-tables",
+    "marked-extended-tabs",
+    "marked-extended-timeline",
+    "marked-extended-typographic"
+  ],
+  "author": {
+    "name": "Fabián Segura",
+    "url": "https://www.fsegurai.com/"
+  },
+  "license": "MIT",
+  "scripts": {
+    "prepare": "rollup -c rollup.config.js",
+    "test:types": "tsd -f spec/index.test-d.ts -t src/index.d.ts"
+  },
+  "peerDependencies": {
+    "marked": ">=13 <16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsegurai/marked-extensions.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fsegurai/marked-extensions/issues"
+  },
+  "homepage": "https://github.com/fsegurai/marked-extensions#readme"
+}

package/src/constants.js ADDED Viewed

@@ -0,0 +1,125 @@
+'use strict';
+export const DEFAULT_OPTIONS = {
+  className: 'markdown-alert',
+  variants: [],
+  injectStyles: true,
+};
+/**
+ * The default configuration for alert variants.
+ */
+export const DEFAULT_VARIANTS = [
+  {
+    type: 'note',
+    icon: '<svg class="octicon octicon-info mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>',
+  },
+  {
+    type: 'tip',
+    icon: '<svg class="octicon octicon-light-bulb mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></svg>',
+  },
+  {
+    type: 'important',
+    icon: '<svg class="octicon octicon-report mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>',
+  },
+  {
+    type: 'warning',
+    icon: '<svg class="octicon octicon-alert mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>',
+  },
+  {
+    type: 'caution',
+    icon: '<svg class="octicon octicon-stop mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>',
+  },
+];
+/**
+ * Default CSS styles for alerts
+ */
+export const DEFAULT_STYLES = `
+  .markdown-alert {
+    padding: 0 1em;
+    margin-bottom: 16px;
+    color: inherit;
+    border-left: 0.25em solid #444c56;
+  }
+  .markdown-alert-title {
+    display: inline-flex;
+    align-items: center;
+    font-weight: 500;
+  }
+  .markdown-alert-note {
+    border-left-color: #539bf5;
+    & > .markdown-alert-title {
+      color: #539bf5;
+      & svg {
+        fill: #539bf5;
+      }
+    }
+  }
+  .markdown-alert-tip {
+    border-left-color: #57ab5a;
+    & > .markdown-alert-title {
+      color: #57ab5a;
+      & svg {
+        fill: #57ab5a;
+      }
+    }
+  }
+  .markdown-alert-important {
+    border-left-color: #986ee2;
+    & > .markdown-alert-title {
+      color: #986ee2;
+      & svg {
+        fill: #986ee2;
+      }
+    }
+  }
+  .markdown-alert-warning {
+    border-left-color: #c69026;
+    & > .markdown-alert-title {
+      color: #c69026;
+      & svg {
+        fill: #c69026;
+      }
+    }
+  }
+  .markdown-alert-caution {
+    border-left-color: #e5534b;
+    & > .markdown-alert-title {
+      color: #e5534b;
+      & svg {
+        fill: #e5534b;
+      }
+    }
+  }
+  .mr-2 {
+    margin-right: 0.5rem;
+  }
+`;
+/**
+ * Default template for rendering alerts
+ */
+export const DEFAULT_TEMPLATE = `
+<div class="{className} {className}-{variant}">
+  <p class="{titleClassName}">{icon}{title}</p>
+  <div class="{className}-content">{content}</div>
+</div>
+`;

package/src/helper.js ADDED Viewed

@@ -0,0 +1,15 @@
+'use strict';
+/**
+ * Returns regex pattern to match alert syntax.
+ */
+export function createSyntaxPattern(type) {
+  return `^(?:\\[!${type.toUpperCase()}])\\s*?\n*`;
+}
+/**
+ * Capitalizes the first letter of a string.
+ */
+export function ucfirst(str) {
+  return str.slice(0, 1).toUpperCase() + str.slice(1).toLowerCase();
+}

package/src/index.d.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { MarkedExtension } from 'marked';
+interface AlertVariant {
+  type: string;
+  icon?: string;
+  title?: string;
+  titleClassName?: string;
+  cssClass?: string;
+}
+/**
+ * Options for customizing alerts
+ */
+export interface AlertOptions {
+  /**
+   * Base class name for alerts
+   * @default 'markdown-alert'
+   */
+  className?: string;
+  /**
+   * Custom variants to override or extend defaults
+   * @default []
+   */
+  variants?: AlertVariant[];
+  /**
+   * Whether to automatically inject CSS styles
+   * @default true
+   */
+  injectStyles?: boolean;
+}
+/**
+ * Creates a Marked.js extension for rendering alert blocks
+ * @param options - Configuration options for the alert extension
+ * @returns A Marked.js extension object
+ */
+export default function markedExtendedAlert(options?: AlertOptions): MarkedExtension;

package/src/index.js ADDED Viewed

@@ -0,0 +1,41 @@
+'use strict';
+import { DEFAULT_OPTIONS } from './constants.js';
+import { ensureStyles } from './styles.js';
+import { processAlertToken } from './tokenizer.js';
+import { renderAlert } from './renderer.js';
+/**
+ * A [marked](https://marked.js.org/) extension to support [GFM alerts](https://github.com/orgs/community/discussions/16925).
+ * @param {Object} options - Configuration options
+ * @param {string} [options.className='markdown-alert'] - Base class name for alerts
+ * @param {Array} [options.variants=[]] - Custom variants to override or extend defaults
+ * @param {boolean} [options.injectStyles=true] - Whether to automatically inject CSS styles
+ * @returns {Object} Marked extension object
+ */
+export default function markedExtendedAlert(options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+  // Resolve variants
+  // Inject styles if needed
+  if (config.injectStyles) ensureStyles();
+  return {
+    walkTokens(token) {
+      if (token.type !== 'blockquote') return;
+      // Process blockquote token for alerts
+      processAlertToken({ token, ...config });
+    },
+    extensions: [
+      {
+        name: 'alert',
+        level: 'block',
+        renderer({ meta, tokens = [] }) {
+          return renderAlert(meta, tokens, this.parser);
+        },
+      },
+    ],
+  };
+}

package/src/renderer.js ADDED Viewed

@@ -0,0 +1,26 @@
+'use strict';
+import { DEFAULT_TEMPLATE } from './constants';
+/**
+ * Renders an alert with the given properties
+ * @param {Object} meta - Metadata for the alert
+ * @param {Array} tokens - Tokens to render within the alert
+ * @param {Object} parser - Parser to use for rendering content
+ * @returns {String} HTML representation of the alert
+ */
+export function renderAlert(meta = {}, tokens = [], parser) {
+  if (!meta) return '';
+  const { className, variant, icon, title, titleClassName } = meta;
+  // Tokenize and then parse the content
+  const markedContent = tokens && tokens.length > 0 ? parser.parse(tokens) : '';
+  return DEFAULT_TEMPLATE.replace(/{className}/g, className)
+    .replace(/{variant}/g, variant)
+    .replace(/{titleClassName}/g, titleClassName)
+    .replace(/{icon}/g, icon)
+    .replace(/{title}/g, title)
+    .replace(/{content}/g, markedContent);
+}

package/src/styles.js ADDED Viewed

@@ -0,0 +1,19 @@
+/* eslint-disable no-undef */
+'use strict';
+import { DEFAULT_STYLES } from './constants.js';
+/**
+ * Adds CSS styles for alerts to the page head if they don't already exist
+ */
+export function ensureStyles() {
+  if (typeof window === 'undefined') return;
+  if (!window.__alertStylesAdded) {
+    const styleEl = document.createElement('style');
+    styleEl.id = 'marked-extended-alert-styles';
+    styleEl.textContent = DEFAULT_STYLES;
+    document.head.appendChild(styleEl);
+    window.__alertStylesAdded = true;
+  }
+}

package/src/tokenizer.js ADDED Viewed

@@ -0,0 +1,78 @@
+'use strict';
+import { DEFAULT_VARIANTS } from './constants.js';
+import { createSyntaxPattern, ucfirst } from './helper.js';
+/**
+ * Process a blockquote token to check and convert it into an alert
+ * @param {Object} options - Configuration options
+ * @param {Object} options.token - The token to process
+ * @param {string} [options.className='markdown-alert'] - Base class name for alerts
+ * @param {Array} [options.variants=[]] - Custom variants to override or extend defaults
+ */
+export function processAlertToken(options = {}) {
+  const { token, className, variants } = options;
+  const resolvedVariants = resolveVariants(variants);
+  const matchedVariant = resolvedVariants.find(({ type }) => new RegExp(createSyntaxPattern(type)).test(token.text));
+  if (!matchedVariant) return;
+  const {
+    type: variantType,
+    icon,
+    title = ucfirst(variantType),
+    titleClassName = `${className}-title`,
+  } = matchedVariant;
+  const typeRegexp = new RegExp(createSyntaxPattern(variantType));
+  // Transform the token into an alert token
+  Object.assign(token, {
+    type: 'alert',
+    meta: {
+      className,
+      variant: variantType,
+      icon,
+      title,
+      titleClassName,
+    },
+  });
+  // Clean up the first line to remove the alert marker
+  const firstLine = token.tokens?.[0];
+  const firstLineText = firstLine?.raw?.replace(typeRegexp, '').trim();
+  if (firstLineText) {
+    const patternToken = firstLine.tokens[0];
+    Object.assign(patternToken, {
+      raw: patternToken.raw.replace(typeRegexp, ''),
+      text: patternToken.text.replace(typeRegexp, ''),
+    });
+    if (firstLine.tokens[1]?.type === 'br') {
+      firstLine.tokens.splice(1, 1);
+    }
+  } else {
+    token.tokens?.shift();
+  }
+}
+/**
+ * Resolves the variants configuration, combining the provided variants with
+ * the default variants.
+ * @param {Array} variants - Custom variants to merge with defaults
+ * @returns {Array} Merged variants
+ */
+function resolveVariants(variants) {
+  if (!variants.length) return DEFAULT_VARIANTS;
+  return Object.values(
+    [...DEFAULT_VARIANTS, ...variants].reduce((map, item) => {
+      map[item.type] = item;
+      return map;
+    }, {}),
+  );
+}