@dr-ishaan/remake-blocks 1.4.2 → 1.4.3

package/README.md

@@ -586,6 +586,102 @@ GFM-only features like tables, autolinks, and task list items require the `remar
 
 ---
 
+## How It Works: Parsing Pipeline
+
+The plugin processes markdown through 4 passes. Each syntax is detected at a different stage:
+
+### Pass overview
+
+| Pass | Name | When it runs | What it detects | Output |
+|------|------|-------------|-----------------|--------|
+| 0a | Directive syntax transformer | `enableDirectiveSyntax: true` | `:::type[Title]{attrs}` ... `:::` paragraphs | Callout HTML node |
+| 0b | MkDocs syntax transformer | `enableMkDocsSyntax: true` | `!!! type`, `??? type`, `???+ type` paragraphs | Callout HTML node |
+| 1 | Blockquote callout transformer | Always runs | `> [!TYPE]` in blockquote nodes | Callout HTML node or enhanced blockquote |
+| 2 | Accordion grouping | `enableAccordion: true` | Consecutive disclosure `<details>` nodes | `<div class="disclosure-accordion">` wrapper |
+
+### Syntax detection methods
+
+| Syntax | How remark-parse sees it | How the plugin detects it | Key parsing logic |
+|--------|------------------------|--------------------------|-------------------|
+| **Blockquote** (`> [!NOTE]`) | `blockquote` → `paragraph` → `text` starting with `[!TYPE]` | Regex on first text child: `^\[!(NOTE\|TIP\|...)\]([+-]?)(title)?({overrides})?` | Dynamically built regex from registered types + aliases + empty string for `[!]` disclosures |
+| **Directive** (`:::note`) | `paragraph` → `text` containing entire `:::type...\n:::` block | `text.startsWith(":::")` → count colons → extract type → parse `[Title]` → parse `{attrs}` → find closing `:::` | String methods (not regex `^` — avoids Node.js anchor issue); body is everything between opening and closing lines |
+| **MkDocs** (`!!! note`) | `paragraph` → `text` containing entire `!!! type\n    body` block | `text.startsWith("!!!")` or `text.startsWith("???")` → extract marker → extract type → parse `"Title"` → body is 4-space indented | String methods; strips 4-space indent from each body line |
+
+### Blockquote callout regex capture groups
+
+| Group | Content | Example | Used for |
+|-------|---------|---------|----------|
+| `[1]` | Type name (or empty for `[!]`) | `note`, `warning`, `""` | Look up callout config or identify as disclosure |
+| `[2]` | Fold marker | `+`, `-`, or `""` | `+` = expanded collapsible, `-` = collapsed, `""` = not collapsible |
+| `[3]` | Custom title text | `Breaking Change` | Override default title |
+| `[4]` | Overrides block | `{icon=false appearance=minimal}` | Parsed by `parseOverrides()` + `parseDirectiveAttrs()` |
+
+### Disclosure widget detection
+
+The `[!]` syntax is detected in the **same blockquote pass** as regular callouts. The key difference is an **empty string** added to the regex alternatives:
+
+| Aspect | Regular callout (`> [!NOTE]`) | Disclosure (`> [!]`) |
+|--------|------------------------------|---------------------|
+| **Type name** | `note`, `warning`, etc. | `disclosure` (synthetic) |
+| **Config lookup** | `configMap.get(type)` → icon, color, className | No config — plain |
+| **Icon** | SVG icon from iconSet | None |
+| **Color** | Per-type border/bg colors | None (gray left line only) |
+| **CSS class** | `callout callout-note` | `disclosure` |
+| **Container** | `<aside>` or `<details>` | Always `<details>` |
+| **Collapsible** | Only if `+`/`-` marker present | Always collapsible |
+| **Default title** | From config (e.g., "Note") | "Details" |
+| **data-callout-type** | `note`, `warning`, etc. | Not set |
+| **role** | `role="note"` | Not set (uses native `<details>`) |
+| **Left accent line** | Colored (matches callout type) | Gray (`#d0d7de`) |
+| **Fold markers** | `+`/`-` = collapsible, none = not collapsible | `+`/none = expanded, `-` = collapsed |
+
+### `{overrides}` block parsing
+
+Two parsers run on the `{...}` block (used by all 3 syntaxes):
+
+| Parser | Input pattern | Output keys | Purpose |
+|--------|--------------|-------------|---------|
+| `parseOverrides()` | `icon=false`, `appearance=minimal`, `inline`, `icon="rocket"` | `overrides.icon`, `overrides.appearance`, `overrides.inline`, `overrides.iconName` | Plugin-specific per-callout visual overrides |
+| `parseDirectiveAttrs()` | `#my-id`, `.custom-class`, `data-x="y"` | `directiveAttrs.id`, `directiveAttrs.classes`, `directiveAttrs.attrs` | remark-directive compatible HTML attributes |
+
+### Override keys reference
+
+| Key | Values | Effect | Example |
+|-----|--------|--------|---------|
+| `icon` | `false`, `true`, `"name"` | Hide icon / show icon / use named Lucide icon | `{icon=false}`, `{icon="rocket"}` |
+| `appearance` | `default`, `minimal`, `simple`, `hidden` | Visual density variant | `{appearance=minimal}` |
+| `inline` | `inline`, `inline-end` (or bare keywords) | Float left / float right (responsive) | `{inline}`, `{inline-end}` |
+| `fold` | `+`, `-` | Collapsible expanded / collapsed (directive syntax only) | `{fold=-}` |
+| `#id` | Any valid HTML id | Sets element id | `{#my-section}` |
+| `.class` | Any valid CSS class name | Adds CSS class | `{.highlight}` |
+| `key="value"` | Any key/value pair | Adds HTML attribute (event handlers and `style` blocked) | `{data-type="example"}` |
+
+### Processing order
+
+| Step | What happens | Why this order |
+|------|-------------|----------------|
+| 1. remark-parse | Raw markdown → mdast tree | Must happen before plugin (external) |
+| 2. Pass 0a: Directive | `:::type` paragraphs → callout HTML | Must run before blockquote pass (directive paragraphs are not blockquotes) |
+| 3. Pass 0b: MkDocs | `!!! type` paragraphs → callout HTML | Same reason — paragraph-level, not blockquote-level |
+| 4. Pass 1: Blockquote | `> [!TYPE]` blockquotes → callout HTML | Processes deepest blockquotes first (inside-out) so nested callouts are resolved before parents |
+| 5. Pass 2: Accordion | Groups consecutive disclosure `<details>` | Must run after all disclosures are rendered |
+
+### `ParsedCallout` object (internal)
+
+All 3 syntaxes produce the same `ParsedCallout` object, which is passed to `buildCalloutHtml()`:
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `type` | `string` | Regex group [1] | Callout type (lowercased) or `"disclosure"` |
+| `customTitle` | `string \| undefined` | Regex group [3] or `[Title]` or `"Title"` | User-provided title (overrides default) |
+| `collapsible` | `boolean` | Fold marker or `???`/`???+` | Whether callout is collapsible |
+| `collapsibleOpen` | `boolean` | `+` marker or `???+` or no marker (disclosures) | Whether collapsible starts expanded |
+| `isDisclosure` | `boolean` | Empty type match | True for `[!]` syntax |
+| `overrides` | `object \| undefined` | `{overrides}` block via `parseOverrides()` | Per-callout icon/appearance/inline overrides |
+| `directiveAttrs` | `object \| undefined` | `{attrs}` block via `parseDirectiveAttrs()` | Per-callout id/class/HTML attributes |
+
+---
+
 ## Advanced: Using the Remark Plugin Directly
 
 The remark plugin can be used independently of the Astro integration:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr-ishaan/remake-blocks",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "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",