@dr-ishaan/remake-blocks 1.4.1 → 1.4.2

package/README.md

@@ -1,35 +1,71 @@
-# remake-blocks
+# @dr-ishaan/remake-blocks
 
-Remark plugin for rendering GitHub-style callouts (admonitions), enhanced blockquotes, and disclosure widgets in Markdown content. Framework-agnostic with an optional Astro integration.
+Astro 6 + remark plugin for rendering GitHub-style callouts (admonitions), enhanced blockquotes, and disclosure widgets in Markdown content — **27 first-class types + 4 themes + inline callouts + directive syntax + safe-by-default HTML escaping + Lucide/emoji icon sets**.
 
-**27 first-class callout types** + plain disclosure widgets — each directive maps 1:1 to its own unique visual identity, SVG icon, color palette, and CSS class. No alias resolution.
+Each directive maps 1:1 to its own unique visual identity, SVG icon, color palette, and CSS class. No alias resolution.
 
 ---
 
 ## Features
 
-- **27 built-in callout types** — GFM standard (5) + Obsidian core (10) + promoted aliases (12), each with unique styling
+### Callout types & syntax
+- **27 built-in callout types** — GFM standard (5) + Obsidian core (10) + promoted aliases (12)
 - **GitHub admonition syntax** — `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, etc.
-- **Custom titles** — `> [!WARNING] Deprecated API` renders with your title
+- **Directive syntax** — `:::note[Title]` ... `:::` (Starlight/Docusaurus compat, opt-in)
+- **MkDocs admonition syntax** — `!!! note`, `??? note`, `???+ note` (MkDocs Material compat, opt-in)
+- **Custom titles** — `> [!WARNING] Deprecated API`
 - **Collapsible callouts** — `> [!FAQ]-` (collapsed) and `> [!TIP]+` (expanded)
-- **Disclosure widgets** — `> [!] Title` creates a plain collapsible block (no color/icon)
+- **Disclosure widgets** — `> [!] Title` creates a plain collapsible block
 - **Accordion grouping** — consecutive `[!]` blocks auto-group into an accordion
 - **Tree view** — nested `[!]` blocks get depth indicators
 - **Custom callout types** — define your own with icon, color, and CSS class
-- **Enhanced blockquotes** — regular blockquotes get improved styling automatically
-- **Dark mode** — automatic via `prefers-color-scheme` and manual via `data-theme` attribute
+- **Configurable aliases** — `aliases: { note: ["n"] }` for short names
+
+### Themes & styling
+- **4 swappable CSS themes** — github, obsidian, vitepress, docusaurus
+- **Inline callouts** — `{inline}` floats left, `{inline-end}` floats right (responsive)
+- **Appearance variants** — `{appearance=minimal}`, `{appearance=hidden}`, etc.
+- **Icon sets** — octicon (default), lucide, emoji, none
+- **Per-callout named icon** — `{icon="rocket"}` uses a specific Lucide icon
+- **Enhanced blockquotes** — rounded left accent line, darker text, auto-styled
+- **i18n label customization** — `labels: { note: "注意" }` for localized titles
+- **Dark mode** — automatic via `prefers-color-scheme` + manual via `data-theme` attribute
 - **Auto CSS injection** — styles injected into every page by default
-- **Zero JavaScript** for callouts — pure CSS + HTML (collapsibles use native `<details>`/`<summary>`)
-- **Accessible** — proper ARIA roles, semantic HTML
+- **CSS custom properties** — full `var()` system for easy customization
+
+### Accessibility (WCAG-compliant)
+- **`role="note"`** for ALL callout types (no `role="alert"` on static content — WCAG fix)
+- **`aria-labelledby`** linking container → title id
+- **`aria-hidden="true"`** on all decorative icons
+- **`dir="auto"`** on container + title (RTL/Unicode support)
+- **`data-collapsible`** attribute on all callout containers
+- **Semantic HTML** — `<aside>` for non-collapsible, `<details>`/`<summary>` for collapsible
+- **Zero JavaScript** for callouts — native HTML5 (collapsibles use `<details>`/`<summary>`)
+- **axe-core verified** — 0 critical/serious violations across all 27 types
+
+### Security (safe-by-default)
+- **HTML escaping** — raw HTML in markdown body is escaped by default
+- **`allowDangerousHtml` opt-in** — set `true` only if you trust your markdown source
+- **`className`/`color` escaping** — prevents attribute breakout from config values
+- **Custom callout config validation** — missing fields use defaults, no crashes
+- **rehype-sanitize schema** — shipped as `sanitize-schema.json` for strict pipelines
+- **Directive attribute security** — event handlers (`on*`) and `style` blocked
+
+### Power-user features
+- **`tags` option** — override container/title/body element names
+- **`props` option** — per-type static or dynamic HTML attributes (function form)
+- **`build()` escape hatch** — full custom render function for total output control
+- **Directive attributes** — `:::note[Title]{#id .class key="value"}` (remark-directive compat)
+- **Exported helpers** — `escapeHtml`, `escapeAttribute`, `sanitizeColor` for `build()` authors
 - **Print-optimized** — clean print styles
-- **Safe-by-default** — raw HTML in markdown is HTML-escaped by default to prevent XSS (set `allowDangerousHtml: true` to opt out)
+- **Single dependency** — only `unist-util-visit`
 
 ---
 
 ## Install
 
 ```bash
-npm install remake-blocks
+npm install @dr-ishaan/remake-blocks
 ```
 
 ## Quick Start (Astro)
@@ -37,7 +73,7 @@ npm install remake-blocks
 ```js
 // astro.config.mjs
 import { defineConfig } from "astro/config";
-import remakeBlocks from "remake-blocks/astro";
+import remakeBlocks from "@dr-ishaan/remake-blocks/astro";
 
 export default defineConfig({
   integrations: [remakeBlocks()],
@@ -62,7 +98,7 @@ Then use callouts in any Markdown or MDX file:
 ```js
 import { unified } from "unified";
 import remarkParse from "remark-parse";
-import { remarkRemakeBlocks } from "remake-blocks";
+import { remarkRemakeBlocks } from "@dr-ishaan/remake-blocks";
 import remarkRehype from "remark-rehype";
 import rehypeStringify from "rehype-stringify";
 
@@ -133,47 +169,77 @@ Consecutive `[!]` blocks are automatically grouped into an accordion. Nested `[!
 
 ## Syntax
 
-### Basic Callout
+### Blockquote callouts (primary syntax)
 
 ```markdown
 > [!NOTE]
 > Content goes here.
-```
-
-### Custom Title
 
-```markdown
 > [!WARNING] Breaking Change
 > The v2 API has been deprecated.
+
+> [!FAQ]-
+> Click to reveal the answer.
+
+> [!TIP]+
+> This starts expanded but can be collapsed.
 ```
 
-### Collapsible (Collapsed)
+### Directive syntax (Starlight/Docusaurus compat)
+
+Opt-in via `enableDirectiveSyntax: true`:
 
 ```markdown
-> [!FAQ]-
-> Click to reveal the answer.
+:::note
+Basic callout.
+:::
+
+:::note[Custom Title]
+With title.
+:::
+
+:::warning{fold=-}
+Collapsed callout.
+:::
+
+:::note[Title]{#my-id .custom-class data-type="example"}
+With full directive attributes.
+:::
 ```
 
-### Collapsible (Expanded)
+### MkDocs admonition syntax (MkDocs Material compat)
+
+Opt-in via `enableMkDocsSyntax: true`:
 
 ```markdown
-> [!TIP]+
-> This starts expanded but can be collapsed.
+!!! note
+    Non-collapsible callout (4-space indented body).
+
+??? note
+    Collapsed callout.
+
+???+ note
+    Expanded collapsible callout.
+
+!!! note "Custom Title"
+    With custom title.
 ```
 
-### Multi-Paragraph
+### Per-callout overrides
+
+Use `{key=value}` syntax after the directive:
 
 ```markdown
-> [!IMPORTANT]
-> First paragraph.
->
-> Second paragraph with **bold** and `code`.
->
-> - List item 1
-> - List item 2
+> [!NOTE]{icon=false}            — hide icon for this callout
+> [!NOTE]{icon="rocket"}         — use a specific Lucide icon
+> [!NOTE]{appearance=minimal}     — minimal appearance variant
+> [!NOTE]{appearance=hidden}      — no title, no icon
+> [!NOTE]{inline}                 — float left (responsive)
+> [!NOTE]{inline-end}             — float right (responsive)
+> [!NOTE]{icon=false inline appearance=minimal}  — multiple overrides
 ```
 
-### Disclosure Widget
+### Disclosure widgets
 
 ```markdown
 > [!] Section Title
@@ -193,56 +259,71 @@ Consecutive `[!]` blocks are automatically grouped into an accordion. Nested `[!
 ```js
 // astro.config.mjs
 import { defineConfig } from "astro/config";
-import remakeBlocks from "remake-blocks/astro";
+import remakeBlocks from "@dr-ishaan/remake-blocks/astro";
 
 export default defineConfig({
   integrations: [
     remakeBlocks({
-      // Whether to auto-inject CSS styles (default: true)
-      injectStyles: true,
-
-      // Whether to enhance regular blockquotes (default: true)
-      enhanceBlockquotes: true,
+      // ── Core ──────────────────────────────────────────────
+      injectStyles: true,              // auto-inject CSS (default: true)
+      enhanceBlockquotes: true,        // style regular blockquotes (default: true)
+      dataCalloutType: true,           // add data-callout-type attribute (default: true)
+      allowDangerousHtml: false,       // ⚠️ safe-by-default HTML escaping (default: false)
 
-      // CSS class for callout container (default: "callout")
+      // ── Callout classes ──────────────────────────────────
       calloutClass: "callout",
-
-      // CSS class for callout title (default: "callout-title")
       calloutTitleClass: "callout-title",
-
-      // CSS class for callout body (default: "callout-body")
       calloutBodyClass: "callout-body",
 
-      // Add data-callout-type attribute (default: true)
-      dataCalloutType: true,
-
-      // ⚠️ SECURITY: Allow raw HTML in markdown to pass through (default: false)
-      // Set to true ONLY if you trust your markdown source AND have sanitized it.
-      // When false (default), raw HTML is HTML-escaped before being placed
-      // in callout bodies to prevent XSS attacks.
-      allowDangerousHtml: false,
-
-      // Disclosure widget options (all default: true)
-      enableDisclosures: true,
-      disclosureClass: "disclosure",
-      disclosureTitleClass: "disclosure-title",
-      disclosureBodyClass: "disclosure-body",
-
-      // Accordion grouping (default: true)
-      enableAccordion: true,
-      accordionClass: "disclosure-accordion",
-
-      // Tree view for nested disclosures (default: true)
-      enableTreeView: true,
-
-      // Custom callout types
+      // ── Disclosure widgets ───────────────────────────────
+      enableDisclosures: true,         // enable [!] syntax (default: true)
+      enableAccordion: true,           // auto-group consecutive [!] (default: true)
+      enableTreeView: true,            // nested [!] tree view (default: true)
+
+      // ── Alternative syntaxes (opt-in) ────────────────────
+      enableDirectiveSyntax: false,    // :::note[Title] syntax (default: false)
+      enableMkDocsSyntax: false,       // !!! note / ??? note syntax (default: false)
+
+      // ── Visual options ───────────────────────────────────
+      showIndicator: true,             // show icons globally (default: true)
+      iconSet: "octicon",              // "octicon" | "lucide" | "emoji" | "none"
+      appearance: "default",           // "default" | "minimal" | "simple" | "hidden"
+
+      // ── i18n labels ──────────────────────────────────────
+      labels: {
+        note: "注意",
+        tip: "ヒント",
+        warning: "警告",
+      },
+
+      // ── Aliases ──────────────────────────────────────────
+      aliases: {
+        note: ["n"],
+        tip: ["t"],
+      },
+
+      // ── Power-user options ───────────────────────────────
+      tags: {                          // override HTML element names
+        container: "aside",
+        title: "div",
+        body: "div",
+      },
+      props: {                         // per-type HTML attributes (static or function)
+        note: { "data-category": "info" },
+        warning: (parsed) => ({ "data-severity": parsed.collapsible ? "collapsible" : "static" }),
+      },
+      build: (parsed, config, bodyHtml, options) => {  // full custom render
+        return `<div class="my-callout">${bodyHtml}</div>`;
+      },
+
+      // ── Custom callout types ─────────────────────────────
       customCallouts: [
         {
-          type: "custom",
-          icon: "🚀",
-          className: "callout-custom",
-          defaultTitle: "Custom",
-          color: "#8b5cf6",
+          type: "machine-learning",
+          icon: "🧠",
+          className: "callout-ml",
+          defaultTitle: "Machine Learning",
+          color: "#7c3aed",
           backgroundColor: "#f5f3ff",
         },
       ],
@@ -253,6 +334,32 @@ export default defineConfig({
 
 ---
 
+## Themes
+
+4 swappable CSS themes are available. Import the one you want:
+
+```js
+// Default (github) — auto-injected when injectStyles: true
+import "@dr-ishaan/remake-blocks/styles.css";
+
+// Or pick a specific theme:
+import "@dr-ishaan/remake-blocks/theme/github.css";       // GitHub style
+import "@dr-ishaan/remake-blocks/theme/obsidian.css";     // Obsidian style
+import "@dr-ishaan/remake-blocks/theme/vitepress.css";    // VitePress style
+import "@dr-ishaan/remake-blocks/theme/docusaurus.css";   // Docusaurus style
+```
+
+Each theme includes:
+- Full light + dark mode (`prefers-color-scheme` + `data-theme` attribute)
+- All 27 callout types with per-type colors
+- Enhanced blockquote styling (rounded left accent line)
+- Disclosure widget styling (card with rounded left accent line)
+- Accordion + tree view styling
+- Inline callout CSS (responsive)
+- Print-optimized styles
+
+---
+
 ## Security: Safe-by-Default
 
 By default, **raw HTML in markdown is HTML-escaped** before being placed in callout bodies. This prevents XSS attacks from untrusted markdown content.
@@ -286,14 +393,30 @@ Only set `allowDangerousHtml: true` if:
 1. You fully trust your markdown source, **AND**
 2. You have sanitized the markdown with a tool like `rehype-sanitize`
 
+### rehype-sanitize schema
+
+A compatible sanitize schema is shipped for strict security pipelines:
+
+```js
+import schema from "@dr-ishaan/remake-blocks/sanitize-schema.json";
+import rehypeSanitize from "rehype-sanitize";
+
+// In your pipeline:
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkRemakeBlocks)
+  .use(remarkRehype, { allowDangerousHtml: true })
+  .use(rehypeSanitize, schema)
+  .use(rehypeStringify);
+```
+
 ### Custom Callout Config Validation
 
 Custom callout configurations are validated and normalized:
 - Missing fields are filled with safe defaults (no crash)
 - `null` or non-object entries are skipped
-- Entries with missing/empty `type` are skipped
-- `className` is HTML-escaped before being placed in the class attribute (prevents attribute breakout)
-- `color` is validated against a safe CSS color pattern (hex, rgb, hsl, var(), named, etc.); invalid values fall back to a default gray
+- `className` is HTML-escaped (prevents attribute breakout)
+- `color` is validated against a safe CSS color pattern; invalid values fall back to gray
 
 ---
 
@@ -321,15 +444,24 @@ If a custom callout's `type` matches a built-in, the built-in is overridden.
 
 ---
 
-## Manual CSS Import
+## i18n Label Customization
 
-If you set `injectStyles: false`, import the stylesheet manually:
+Override default titles for any callout type — useful for non-English documentation:
 
 ```js
-// In a layout component or global CSS file
-import "remake-blocks/styles.css";
+remakeBlocks({
+  labels: {
+    note: "注意",
+    tip: "ヒント",
+    warning: "警告",
+    caution: "危険",
+    important: "重要",
+  },
+})
 ```
 
+Works with all 27 builtin types, custom callout types, and all 3 syntaxes (blockquote, directive, MkDocs).
+
 ---
 
 ## Dark Mode
@@ -373,9 +505,10 @@ See `styles.css` for the complete list of CSS custom properties.
 Each callout renders as:
 
 ```html
-<aside class="callout callout-note" data-callout-type="note" role="note">
-  <div class="callout-title" style="color:#0969da">
-    <span class="callout-icon" style="color:#0969da">
+<aside class="callout callout-note" data-callout-type="note" data-collapsible="false"
+       role="note" aria-labelledby="callout-note-1" dir="auto">
+  <div class="callout-title" style="color:#0969da" id="callout-note-1" dir="auto">
+    <span class="callout-icon" style="color:#0969da" aria-hidden="true">
       <!-- SVG icon -->
     </span>
     <span class="callout-title-text">Note</span>
@@ -389,9 +522,10 @@ Each callout renders as:
 Collapsible callouts use `<details>`/`<summary>`:
 
 ```html
-<details class="callout callout-faq collapsible" data-callout-type="faq" role="note">
-  <summary class="callout-title" style="color:#b45309">
-    <span class="callout-icon" style="color:#b45309"><!-- SVG --></span>
+<details class="callout callout-faq collapsible" data-callout-type="faq" data-collapsible="true"
+         role="note" aria-labelledby="callout-faq-1" dir="auto">
+  <summary class="callout-title" style="color:#b45309" id="callout-faq-1" dir="auto">
+    <span class="callout-icon" style="color:#b45309" aria-hidden="true"><!-- SVG --></span>
     <span class="callout-title-text">FAQ</span>
   </summary>
   <div class="callout-body">
@@ -402,11 +536,27 @@ Collapsible callouts use `<details>`/`<summary>`:
 
 ---
 
+## Exported Helpers
+
+For users who supply a custom `build()` render function:
+
+```js
+import { escapeHtml, escapeAttribute, sanitizeColor } from "@dr-ishaan/remake-blocks";
+```
+
+| Helper | Description |
+|--------|-------------|
+| `escapeHtml(str)` | Escapes `& < > " '` to HTML entities |
+| `escapeAttribute(str)` | Same as `escapeHtml`, for attribute values |
+| `sanitizeColor(value, fallback)` | Validates CSS color; returns fallback if dangerous |
+
+---
+
 ## Caveats
 
 ### Strikethrough (`~~text~~`) requires `remark-gfm`
 
-The plugin's body serializer handles `<del>` nodes correctly, but `remark-parse` alone does **not** enable GFM strikethrough. To use `~~strikethrough~~` syntax in callout bodies, add `remark-gfm` to your Astro config:
+The plugin's body serializer handles `<del>` nodes correctly, but `remark-parse` alone does **not** enable GFM strikethrough. To use `~~strikethrough~~` syntax in callout bodies, add `remark-gfm`:
 
 ```js
 import remarkGfm from "remark-gfm";
@@ -419,14 +569,7 @@ export default defineConfig({
 
 ### Horizontal rule after directive becomes a setext H2
 
-In CommonMark, this markdown:
-
-```markdown
-> [!NOTE]
-> ---
-```
-
-is interpreted as a setext H2 heading ("[!NOTE]" with `---` underline), **not** as a callout with a thematic break body. To get a thematic break in the body, add a blank line before `---`:
+In CommonMark, `> [!NOTE]\n> ---` is interpreted as a setext H2 heading, **not** as a callout with a thematic break body. Add a blank line before `---`:
 
 ```markdown
 > [!NOTE]
@@ -439,7 +582,7 @@ is interpreted as a setext H2 heading ("[!NOTE]" with `---` underline), **not**
 
 ### Tables and other GFM features require `remark-gfm`
 
-GFM-only features like tables, autolinks, and task list items require the `remark-gfm` plugin. The plugin's body serializer handles them when `remark-gfm` produces the appropriate mdast nodes.
+GFM-only features like tables, autolinks, and task list items require the `remark-gfm` plugin.
 
 ---
 
@@ -450,7 +593,7 @@ The remark plugin can be used independently of the Astro integration:
 ```js
 import { unified } from "unified";
 import remarkParse from "remark-parse";
-import { remarkRemakeBlocks } from "remake-blocks";
+import { remarkRemakeBlocks } from "@dr-ishaan/remake-blocks";
 
 const processor = unified()
   .use(remarkParse)
@@ -460,7 +603,7 @@ const processor = unified()
 A backward-compatible alias `remarkCalloutBlocks` is also exported:
 
 ```js
-import { remarkCalloutBlocks } from "remake-blocks";
+import { remarkCalloutBlocks } from "@dr-ishaan/remake-blocks";
 ```
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dr-ishaan/remake-blocks",
-  "version": "1.4.1",
-  "description": "Astro 6 + remark plugin for GitHub-style callouts (admonitions), enhanced blockquotes, and disclosure widgets — 27 first-class types + 4 themes + inline callouts + directive syntax + safe-by-default HTML escaping + Lucide/emoji icon sets",
+  "version": "1.4.2",
+  "description": "Astro 6 + remark plugin — 27 callout types, 4 themes, disclosure widgets, inline callouts, directive syntax, MkDocs syntax, i18n labels, safe-by-default XSS escaping, WCAG accessibility, Lucide/emoji icons",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",