@wgtechlabs/mdd-engine 0.1.0-pr.cab0713 → 0.1.0-pr.d58d6d6

package/README.md

@@ -84,16 +84,19 @@ order: 1
 ---
 # Installation
 
-:::note[Before you start]
-You need a local documentation project.
-:::
+> [!NOTE]
+> **Before you start**
+>
+> You need a local documentation project.
 
 :::details[More information]
 Ordinary **Markdown** works inside components.
 :::
 ```
 
-Use `note`, `tip`, `warning`, or `details` containers. Labels are optional; attributes and unknown component names are errors. Callouts become semantic `aside` elements, disclosures become `details`/`summary`, and each has a stable `mdd-<component>` class. Readable Markdown uses blockquotes with bold labels, without executable content.
+Use GitHub-style alerts with `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, or `CAUTION`. Put the exact uppercase marker on the opening line of a blockquote at the document root; nested blockquotes remain ordinary quotes. Alerts become semantic `aside` elements with `mdd-alert` and `mdd-<type>` classes. Their readable Markdown preserves the `> [!TYPE]` marker. The engine supplies meaning and labels; the reader composes the article, and themes supply icons and colors.
+
+`:::details[More information]` remains supported and becomes `details`/`summary`; its label is optional, attributes are errors, and its readable Markdown uses a blockquote with a bold label. The old `:::note`, `:::tip`, and `:::warning` directives now fail with a `REMOVED_COMPONENT` migration diagnostic. See [alerts and migration](docs/ALERTS.md) for all five types, theme hooks, and how to preserve custom titles and bodies.
 
 Title precedence is frontmatter title, first H1, then readable filename. Navigation uses `navTitle` when supplied. Explicit `order` sorts first; remaining siblings sort deterministically by label and path.
 

package/dist/alerts.d.ts

@@ -0,0 +1,8 @@
+import type { Root } from "mdast";
+declare module "mdast" {
+    interface TextData {
+        mddAlertMarker?: true;
+    }
+}
+/** Recognize alerts only at the document root, using unescaped source syntax. */
+export declare function transformAlerts(tree: Root, source: string): void;

package/dist/alerts.js

@@ -0,0 +1,56 @@
+/** Recognize alerts only at the document root, using unescaped source syntax. */
+export function transformAlerts(tree, source) {
+    for (const node of tree.children) {
+        if (node.type !== "blockquote")
+            continue;
+        const paragraph = node.children[0];
+        const first = paragraph?.type === "paragraph" ? paragraph.children[0] : undefined;
+        const offset = paragraph?.position?.start.offset;
+        if (paragraph?.type !== "paragraph" ||
+            first?.type !== "text" ||
+            offset === undefined ||
+            paragraph.position?.start.line !== node.position?.start.line)
+            continue;
+        const marker = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][\t ]*(?:\r\n|\r|\n|$)/.exec(source.slice(offset));
+        const kind = marker?.[1];
+        if (!kind)
+            continue;
+        first.value = first.value.slice(kind.length + 3);
+        const bodyStart = paragraph.children[0];
+        if (bodyStart?.type === "text") {
+            bodyStart.value = bodyStart.value.replace(/^[\t ]*(?:\r\n|\r|\n)?/, "");
+            if (!bodyStart.value)
+                paragraph.children.shift();
+        }
+        if (paragraph.children[0]?.type === "break")
+            paragraph.children.shift();
+        if (!paragraph.children.length)
+            node.children.shift();
+        const type = kind.toLowerCase();
+        const label = type.charAt(0).toUpperCase() + type.slice(1);
+        const markerText = {
+            type: "text",
+            value: `[!${kind}]`,
+            data: { mddAlertMarker: true },
+        };
+        node.children.unshift({
+            type: "paragraph",
+            children: [markerText],
+            data: {
+                hProperties: { className: ["mdd-component-label"] },
+                hChildren: [
+                    {
+                        type: "element",
+                        tagName: "strong",
+                        properties: {},
+                        children: [{ type: "text", value: label }],
+                    },
+                ],
+            },
+        });
+        node.data = {
+            hName: "aside",
+            hProperties: { className: ["mdd-alert", `mdd-${type}`] },
+        };
+    }
+}

package/dist/markdown.js

@@ -12,6 +12,7 @@ import remarkStringify from "remark-stringify";
 import { unified } from "unified";
 import { SKIP, visit } from "unist-util-visit";
 import { parseDocument as parseYaml } from "yaml";
+import { transformAlerts } from "./alerts.js";
 const parser = unified()
     .use(remarkParse)
     .use(remarkGfm)
@@ -44,8 +45,19 @@ const htmlRenderer = unified()
     },
 })
     .use(rehypeStringify);
-const markdownRenderer = unified().use(remarkGfm).use(remarkStringify);
-const componentNames = new Set(["note", "tip", "warning", "details"]);
+const markdownRenderer = unified()
+    .use(remarkGfm)
+    .use(remarkStringify, {
+    handlers: {
+        text(node, _parent, state, info) {
+            // Only generated alert markers bypass normal Markdown escaping.
+            return node.data?.mddAlertMarker === true
+                ? node.value
+                : state.safe(node.value, info);
+        },
+    },
+});
+const removedNotices = new Set(["note", "tip", "warning"]);
 /** Keep the same first-wins, reachable definitions that the HTML renderer uses. */
 function retainReferencedDefinitions(tree) {
     const definitions = new Map();
@@ -100,6 +112,7 @@ function unsafeUrl(url, image) {
 }
 export function parseDocument(source, file, diagnostics) {
     const tree = parser.parse(source);
+    transformAlerts(tree, source);
     retainReferencedDefinitions(tree);
     const metadata = {};
     const headings = [];
@@ -185,8 +198,12 @@ export function parseDocument(source, file, diagnostics) {
             node.type !== "textDirective") {
             return;
         }
-        if (node.type !== "containerDirective" || !componentNames.has(node.name)) {
-            report("UNKNOWN_COMPONENT", `Unsupported component ${node.name}; use a note, tip, warning, or details container.`, node);
+        if (removedNotices.has(node.name)) {
+            report("REMOVED_COMPONENT", `The ${node.name} directive was removed; use > [!${node.name.toUpperCase()}] followed by quoted body lines. Keep any optional custom title as bold text in the alert body.`, node);
+            return;
+        }
+        if (node.type !== "containerDirective" || node.name !== "details") {
+            report("UNKNOWN_COMPONENT", `Unsupported component ${node.name}; use a GitHub alert or a details container.`, node);
             return;
         }
         if (Object.keys(node.attributes ?? {}).length) {
@@ -195,7 +212,7 @@ export function parseDocument(source, file, diagnostics) {
         if (index === undefined || !parent)
             return;
         const first = node.children[0];
-        const defaultLabel = node.name.charAt(0).toUpperCase() + node.name.slice(1);
+        const defaultLabel = "Details";
         const label = first?.type === "paragraph" && first.data?.directiveLabel
             ? first
             : {
@@ -214,7 +231,7 @@ export function parseDocument(source, file, diagnostics) {
         }
         label.children = [{ type: "strong", children: label.children }];
         label.data = {
-            hName: node.name === "details" ? "summary" : "p",
+            hName: "summary",
             hProperties: { className: ["mdd-component-label"] },
         };
         parent.children[index] = {
@@ -222,8 +239,8 @@ export function parseDocument(source, file, diagnostics) {
             children: node.children,
             position: node.position,
             data: {
-                hName: node.name === "details" ? "details" : "aside",
-                hProperties: { className: [`mdd-${node.name}`] },
+                hName: "details",
+                hProperties: { className: ["mdd-details"] },
             },
         };
         // Revisit the replacement so nested content is validated exactly once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wgtechlabs/mdd-engine",
-  "version": "0.1.0-pr.cab0713",
+  "version": "0.1.0-pr.d58d6d6",
   "description": "Headless Markdown documentation compiler for mdd",
   "type": "module",
   "license": "MIT",