auwla-markdown 0.0.1

package/README.md

@@ -0,0 +1,301 @@
+# `@auwla/markdown`
+
+A zero-dependency, type-safe Markdown compilation engine with custom component tags, code-block filename headers, line-highlighting, and interactive tabs. Designed for premium developer documentation and Static Site Generation (SSG).
+
+> [!NOTE]
+> **Full Standard Markdown Support:** `@auwla/markdown` is completely backward-compatible. It supports all default, standard Markdown documents (fences, headings, lists, bold text) out of the box. Our custom tag-based component syntax (`=<TagName>`) is designed as a completely **optional layer** to improve markup readability and provide advanced UI customizations (like tabs, collapsible callouts, and customized tables).
+
+---
+
+## 🚀 Key Features
+
+*   **Visual Component Tags (`=<TagName>`):** Dynamic components registry with built-in or custom elements.
+*   **Header Metadata:** `=<Header>` block strips frontmatter configuration from HTML body automatically.
+*   **Collapsible Callouts:** Native `<details>`/`<summary>` card blocks.
+*   **Tag-Based Tab Panels:** Multi-tab toggle sections using `=<Tabs>` and `=<Tab>`.
+*   **Zero Client-Side JS Overhead:** Interactive UI elements use tiny, inline, vanilla handlers.
+*   **Code Blocks Meta:** Support filename badges `[Counter.tsx]` and line range highlights `{7-9}`.
+*   **Header Anchors:** Self-linking `#` anchors generated for both markdown and tag-based headings.
+
+---
+
+## 📦 Getting Started
+
+### 1. Install the Package
+
+```bash
+bun add @auwla/markdown
+# or npm install @auwla/markdown
+```
+
+### 2. Initialize the Compiler Configuration
+
+Create a markdown parser configuration file:
+
+```typescript
+// src/markdown.config.ts
+import { createMDConfig, shikiHighlighter } from '@auwla/markdown';
+
+export const mdParser = createMDConfig({
+  // Pluggable highlighter adapter (runs at compile-time)
+  highlighter: shikiHighlighter({
+    theme: 'github-dark',
+    langs: ['typescript', 'tsx', 'javascript', 'jsx', 'bash', 'html', 'css']
+  }),
+
+  // Toggle built-in features
+  features: {
+    copyCodeButton: true,  // Adds interactive "Copy" button to code blocks
+    headerAnchors: true    // Appends self-linking hover anchors (#) to headings
+  },
+
+  // Register custom component tags
+  components: {
+    MyCard: (props, rawContent, parse) => `
+      <div class="card ${props.theme || 'light'}">
+        <h3>${props.title}</h3>
+        <div class="body">${parse(rawContent)}</div>
+      </div>
+    `
+  }
+});
+```
+
+---
+
+## 📑 `=<Header>` Metadata Syntax
+
+Traditional frontmatter YAML markers (`---`) are replaced by the `=<Header>` block placed at the **very top of the file**:
+
+```markdown
+=<Header>
+title: Premium Documentation Guide
+author: Amihere Theophilus Junior
+version: 1.0.0
+draft: false
+=</Header>
+```
+
+### Metadata Features:
+*   **Parsing & Extraction:** The parsed fields are returned programmatically under the `meta` key.
+*   **HTML Stripping:** The entire `=<Header>` block is stripped completely from the returned HTML body so it never renders inside page content.
+
+---
+
+## 🧩 Built-in Component Tags
+
+All custom tags start with `=<` and close with `=</TagName>` or are self-closing `/>`.
+
+### Customization & Attribute Forwarding:
+Every built-in tag supports **easy CSS class targeting** and **raw HTML attribute forwarding**:
+*   **Class name merging:** If you pass `class="..."` on any tag, the custom class names are automatically appended to the component's default class name (e.g. `<div class="callout callout-note my-custom-class">`).
+*   **HTML attribute forwarding:** Any custom HTML properties (like `style="..."`, `colspan="..."`, `rowspan="..."`) passed to a component are directly forwarded to the compiled HTML tag (e.g. `<table class="auwla-table" style="color: red;">`).
+
+---
+
+### 1. `=<Callout>`
+Displays highlighted message blocks.
+
+*   **Attributes:**
+    *   `type`: Modifies color theme border. Supported: `note`, `tip`, `important`, `warning`, `caution`. (Default: `note`).
+    *   `title`: Overrides default uppercase header text.
+    *   `collapsible`: Boolean or presence marker (`collapsible`, `collapsible="true"`). If present, compiles to native interactive `<details>` and `<summary>` elements.
+    *   `collapsed`: Boolean (`"true"` / `"false"`). If collapsible, sets whether it is closed by default.
+    *   `class`: Custom classes merged onto the element wrapper.
+    *   *Additional attributes:* Any other attribute (e.g. `style="..."`) is forwarded directly.
+
+```markdown
+/* Simple Standard Callout */
+=<Callout type="note" title="Useful Note">
+This is a standard callout.
+=</Callout>
+
+/* Interactive Collapsible Callout */
+=<Callout type="tip" title="Advanced Tip" collapsible>
+Here is some detailed compilation info that is collapsed by default.
+=</Callout>
+```
+
+---
+
+### 2. `=<Tabs>` and `=<Tab>`
+Renders selection tabs with zero-dependency toggle buttons.
+
+*   **`=<Tabs>`** (Parent Container): Parses nested panels and binds click state handlers. Supports `class` and `style` forwarding.
+*   **`=<Tab>`** (Panel):
+    *   `title`: The label displayed on the tab button (required).
+    *   Supports `class` and `style` forwarding (e.g., custom tab panels).
+
+```markdown
+=<Tabs class="my-custom-tabs">
+  =<Tab title="TSX Component" class="first-panel">
+```tsx [Counter.tsx]
+import { reactive } from 'auwla';
+export default function Counter() { ... }
+```
+  =</Tab>
+
+  =<Tab title="Bash CLI">
+```bash
+bun install @auwla/markdown
+```
+  =</Tab>
+=</Tabs>
+```
+
+---
+
+### 3. Custom Tables (`=<Table>`, `=<Row>`, `=<Column>`, `=<Cell>`)
+Structural tag-based table elements.
+
+*   **`=<Table>`** (Wrapper): Accepts table attributes (like `border="1"`, `class`, or `style`).
+*   **`=<Row>`** (Row): Compiles to `<tr>`. Supports class/style forwarding.
+*   **`=<Column>`** (Header Cell): Compiles to `<th>`. Supports `align` (`"left"`, `"center"`, `"right"`), `colspan`, `rowspan`, class, and style.
+*   **`=<Cell>`** (Data Cell): Compiles to `<td>`. Supports `align` (`"left"`, `"center"`, `"right"`), `colspan`, `rowspan`, class, and style.
+
+```markdown
+=<Table style="color: red;">
+  =<Row class="header-row">
+    =<Column align="left" colspan="2">Framework Details=</Column>
+  </Row>
+  =<Row>
+    =<Cell align="left">**Auwla**=</Cell>
+    =<Cell align="center">~7 kB=</Cell>
+  </Row>
+</Table>
+```
+
+---
+
+### 4. Custom Headings (`=<h1>` through `=<h6>`)
+Component-driven headings:
+*   **Auto-generated IDs:** Heading text is slugified to generate `id="..."` attributes automatically.
+*   **Custom IDs:** Custom identifiers are preserved if defined explicitly on the tag (e.g. `=<h2 id="custom-anchor">`).
+*   **Hover Anchors:** Self-linking `#` anchors are injected inside heading elements when `features.headerAnchors` is enabled.
+
+```markdown
+=<h1>Getting Started=</h1>
+```
+
+---
+
+### 5. Fallback Wrappers (Lowercase Tags)
+Standard lowercase HTML tag markers (e.g., `=<p>`, `=<span>`, `=<a>`) can be written directly:
+*   **No Double Nesting:** Children inside standard inline wrapper tags (like `p`, `span`, `h1`-`h6`, `li`, `a`) are compiled in **inline mode** to prevent double-block wrapping (e.g., `<p><p>...</p></p>`).
+
+---
+
+## 📝 Code Block Metadata
+
+Annotations are parsed directly from the language fence:
+*   **Filename badge:** Add square brackets `[filename.ext]` to render a filename tab header above the code block.
+*   **Line Highlights:** Add curly braces `{range}` (e.g. `{1-3,5}`) to highlight specific lines.
+
+```typescript
+```tsx [Counter.tsx] {3,5-7}
+import { reactive } from 'auwla';
+// This line is highlighted
+const a = 1;
+// These lines are highlighted
+const b = 2;
+const c = 3;
+```
+```
+
+---
+
+## 💅 Styling Class Schema
+
+Styling class names generated in the HTML output:
+
+| Component | Class Name | Description |
+| :--- | :--- | :--- |
+| **Callout** | `.auwla-callout` | Main card element. |
+| **Callout Type** | `.auwla-callout-note` | Modifier class based on `type="..."`. |
+| **Callout Title** | `.auwla-callout-title` | Title bar elements. |
+| **Callout Content** | `.auwla-callout-content` | Wrapped markdown content body. |
+| **Tabs Wrapper** | `.auwla-tabs-container` | Main tab selector wrapper. |
+| **Tabs Header** | `.auwla-tabs-header` | Row containing tab buttons. |
+| **Tab Button** | `.auwla-tab-btn` | Interactive tab toggle button. |
+| **Active Tab** | `.auwla-tab-btn.active` | Target tab state. |
+| **Tab Panel** | `.auwla-tab-panel` | Display body container. |
+| **Table** | `.auwla-table` | Global table selector class name. |
+| **Header Anchor** | `.header-anchor` | Hoverable link symbol pointing to heading IDs. |
+| **Copy Button** | `.copy-code-btn` | Interactive absolute-positioned copy button. |
+| **Code Wrapper** | `.code-block-wrapper` | Relative div wrapper surrounding pre/code blocks. |
+| **Code Filename** | `.code-block-filename` | Header text element showing the filename. |
+| **Line Highlight** | `.highlighted-line` | Highlighted code line helper class. |
+
+---
+
+## 🛠️ Framework Integration Examples
+
+`@auwla/markdown` compiles down to plain HTML and metadata objects, making it compatible with any modern JS framework.
+
+### 1. Vanilla JS / Node / Bun
+
+```typescript
+import { mdParser } from './markdown.config';
+
+const rawMarkdown = `
+=<Header>
+title: Standalone Markdown Engine
+=</Header>
+# Welcome
+`;
+
+const { html, meta, headings } = await mdParser.parse(rawMarkdown);
+console.log(meta.title); // "Standalone Markdown Engine"
+console.log(html);       // "<h1>Welcome</h1>"
+```
+
+### 2. Svelte / React / Solid (Dynamic Render)
+
+Pass the generated HTML string directly to your framework's raw HTML injector:
+
+```tsx
+// React / Solid
+export function DocView({ html }) {
+  return <article dangerouslySetInnerHTML={{ __html: html }} />;
+}
+```
+
+```svelte
+<!-- Svelte -->
+<article>
+  {@html html}
+</article>
+```
+
+### 3. Static Site Generation (SSG) in Auwla
+
+```tsx
+// src/pages/docs/[slug].tsx
+import { getRouted, type RouteContext } from 'auwla/router';
+import { mdParser } from '../../markdown.config';
+
+export const config = {
+  renderMode: 'ssg',
+  async generatePaths() {
+    return [{ slug: 'introduction' }, { slug: 'installation' }];
+  }
+};
+
+export async function routed(ctx: RouteContext<'/docs/:slug'>) {
+  const rawMarkdown = await loadMarkdownFile(ctx.params.slug);
+  const { html, meta, headings } = await mdParser.parse(rawMarkdown);
+  return { html, meta, headings };
+}
+
+export default function DocPage() {
+  const data = getRouted(routed)?.value;
+  if (!data) return () => <div>Loading...</div>;
+
+  return () => (
+    <div class="docs-layout">
+      <h1>{data.meta.title}</h1>
+      <article dangerouslySetInnerHTML={{ __html: data.html }} />
+    </div>
+  );
+}
+```

package/bun.lock

@@ -0,0 +1,131 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "markdown",
+      "dependencies": {
+        "marked": "^18.0.5",
+        "marked-highlight": "^2.2.4",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "@types/prismjs": "^1.26.6",
+        "prismjs": "^1.30.0",
+        "shiki": "^4.3.0",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@shikijs/core": ["@shikijs/core@4.3.0", "", { "dependencies": { "@shikijs/primitive": "4.3.0", "@shikijs/types": "4.3.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4", "hast-util-to-html": "^9.0.5" } }, "sha512-EooU3i9F6IAE8kEu+AnGf9DFZWkQBZ+hJn3tLVbsH+61mtQiva5biai66fAA6nvFPXkLgvrh7BrR7YcJU83xQQ=="],
+
+    "@shikijs/engine-javascript": ["@shikijs/engine-javascript@4.3.0", "", { "dependencies": { "@shikijs/types": "4.3.0", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^4.3.6" } }, "sha512-hTv/KiFf2tpiqlACPiztGGurEARWIutB8YUhcrA1pUC7VzzwKO+g5crUocrLztrZ5ro5Z4hbXg7bYclETn3gSQ=="],
+
+    "@shikijs/engine-oniguruma": ["@shikijs/engine-oniguruma@4.3.0", "", { "dependencies": { "@shikijs/types": "4.3.0", "@shikijs/vscode-textmate": "^10.0.2" } }, "sha512-1vMdN3gHfnKfLYwecUI2ITJI4RhHt96xEaJumVn7Heb0IlJ8WQMIH0Voak+2j22BpSNKdnOfB/pCTPnPm2gq7A=="],
+
+    "@shikijs/langs": ["@shikijs/langs@4.3.0", "", { "dependencies": { "@shikijs/types": "4.3.0" } }, "sha512-rnlqFbBRSys9bT4gl/5rw9RnS0W/I84ZldXPkO7cvlEMoV85TyF/aU01N7/NbSR776RNLjrJKjfFUXJR6wN1Cg=="],
+
+    "@shikijs/primitive": ["@shikijs/primitive@4.3.0", "", { "dependencies": { "@shikijs/types": "4.3.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-CPkz64PTa5diRW1ggzMZH9VM/du4RNChYgVtgqrFcgruvIybmCvySv8GkiHSczUHXYuuR8TdKEwFx+UnZMpgdg=="],
+
+    "@shikijs/themes": ["@shikijs/themes@4.3.0", "", { "dependencies": { "@shikijs/types": "4.3.0" } }, "sha512-Avgt05YiT+Y3prjIc9lmQxhJzHBcCfR6cjiFW4OyaMBbt2A6trX5rfjUzx+Vj/mE9qpArYjatnqo9XPjQNW/AQ=="],
+
+    "@shikijs/types": ["@shikijs/types@4.3.0", "", { "dependencies": { "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-oc8b9U2SYvofKZk8e/737nIX0qwf6eV2vHFATeObAu7r+mUVpLs8Re0BmVkIjAWAYgkmG/CzLNo7rzuBzRu/wQ=="],
+
+    "@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg=="],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ=="],
+
+    "@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA=="],
+
+    "@types/node": ["@types/node@26.0.1", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-fc3KiUoBt6kie0N9bIW3E47vZsuaMf0PM2AaUpLCLT0s/LvX1nxAim6Fc049cNxODPpGm6qRAuUOB86SkRuPQw=="],
+
+    "@types/prismjs": ["@types/prismjs@1.26.6", "", {}, "sha512-vqlvI7qlMvcCBbVe0AKAb4f97//Hy0EBTaiW8AalRnG/xAN5zOiWWyrNqNXeq8+KAuvRewjCVY1+IPxk4RdNYw=="],
+
+    "@types/unist": ["@types/unist@3.0.3", "", {}, "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q=="],
+
+    "@ungap/structured-clone": ["@ungap/structured-clone@1.3.2", "", {}, "sha512-5jsZFwgR5rTdKwidH9Qmat75RKwqfpKlWWB1frDkljN127mwqBu8K0PYo7/hFpF03IEJpfVPpCQDY/eDx3iHvA=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
+
+    "character-entities-html4": ["character-entities-html4@2.1.0", "", {}, "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA=="],
+
+    "character-entities-legacy": ["character-entities-legacy@3.0.0", "", {}, "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ=="],
+
+    "comma-separated-tokens": ["comma-separated-tokens@2.0.3", "", {}, "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg=="],
+
+    "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
+
+    "devlop": ["devlop@1.1.0", "", { "dependencies": { "dequal": "^2.0.0" } }, "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA=="],
+
+    "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
+
+    "hast-util-whitespace": ["hast-util-whitespace@3.0.0", "", { "dependencies": { "@types/hast": "^3.0.0" } }, "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw=="],
+
+    "html-void-elements": ["html-void-elements@3.0.0", "", {}, "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg=="],
+
+    "marked": ["marked@18.0.5", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w=="],
+
+    "marked-highlight": ["marked-highlight@2.2.4", "", { "peerDependencies": { "marked": ">=4 <19" } }, "sha512-PZxisNMJDduSjc0q6uvjsnqqHCXc9s0eyzxDO9sB1eNGJnd/H1/Fu+z6g/liC1dfJdFW4SftMwMlLvsBhUPrqQ=="],
+
+    "mdast-util-to-hast": ["mdast-util-to-hast@13.2.1", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/mdast": "^4.0.0", "@ungap/structured-clone": "^1.0.0", "devlop": "^1.0.0", "micromark-util-sanitize-uri": "^2.0.0", "trim-lines": "^3.0.0", "unist-util-position": "^5.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA=="],
+
+    "micromark-util-character": ["micromark-util-character@2.1.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q=="],
+
+    "micromark-util-encode": ["micromark-util-encode@2.0.1", "", {}, "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw=="],
+
+    "micromark-util-sanitize-uri": ["micromark-util-sanitize-uri@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ=="],
+
+    "micromark-util-symbol": ["micromark-util-symbol@2.0.1", "", {}, "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q=="],
+
+    "micromark-util-types": ["micromark-util-types@2.0.2", "", {}, "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA=="],
+
+    "oniguruma-parser": ["oniguruma-parser@0.12.2", "", {}, "sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw=="],
+
+    "oniguruma-to-es": ["oniguruma-to-es@4.3.6", "", { "dependencies": { "oniguruma-parser": "^0.12.2", "regex": "^6.1.0", "regex-recursion": "^6.0.2" } }, "sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA=="],
+
+    "prismjs": ["prismjs@1.30.0", "", {}, "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw=="],
+
+    "property-information": ["property-information@7.2.0", "", {}, "sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg=="],
+
+    "regex": ["regex@6.1.0", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg=="],
+
+    "regex-recursion": ["regex-recursion@6.0.2", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg=="],
+
+    "regex-utilities": ["regex-utilities@2.3.0", "", {}, "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng=="],
+
+    "shiki": ["shiki@4.3.0", "", { "dependencies": { "@shikijs/core": "4.3.0", "@shikijs/engine-javascript": "4.3.0", "@shikijs/engine-oniguruma": "4.3.0", "@shikijs/langs": "4.3.0", "@shikijs/themes": "4.3.0", "@shikijs/types": "4.3.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-NKKjWzR6LIGL3sXBrWDw9sDS9cxx42/DkysaNqJEeOWE8Kix5gpak0bc00OfDVEO4oyXSyz8+aRaqKoBD1yo7A=="],
+
+    "space-separated-tokens": ["space-separated-tokens@2.0.2", "", {}, "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q=="],
+
+    "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
+
+    "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+
+    "unist-util-is": ["unist-util-is@6.0.1", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g=="],
+
+    "unist-util-position": ["unist-util-position@5.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA=="],
+
+    "unist-util-stringify-position": ["unist-util-stringify-position@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ=="],
+
+    "unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="],
+
+    "unist-util-visit-parents": ["unist-util-visit-parents@6.0.2", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0" } }, "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ=="],
+
+    "vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q=="],
+
+    "vfile-message": ["vfile-message@4.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw=="],
+
+    "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "auwla-markdown",
+  "version": "0.0.1",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/prismjs": "^1.26.6",
+    "prismjs": "^1.30.0",
+    "shiki": "^4.3.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "peerDependenciesMeta": {
+    "shiki": {
+      "optional": "true"
+    },
+    "prismjs": {
+      "optional": "true"
+    }
+  },
+  "dependencies": {
+    "marked": "^18.0.5",
+    "marked-highlight": "^2.2.4"
+  }
+}

package/src/adapters/shiki.ts

@@ -0,0 +1,42 @@
+import type { HighlighterAdapter } from '../types';
+import type { BundledLanguage, BundledTheme, Highlighter } from 'shiki';
+
+export interface ShikiAdapterOptions {
+  theme?: BundledTheme | { light: BundledTheme; dark: BundledTheme };
+  langs?: BundledLanguage[]; // Pre-load specific languages for speed
+}
+
+export function shikiHighlighter(options: ShikiAdapterOptions = {}): HighlighterAdapter {
+  let shikiInstance: Highlighter | null = null;
+  const theme = options.theme || 'github-dark';
+
+  return async (code: string, language: string) => {
+    // 1. Dynamically import Shiki ONLY when this function is actually called
+    const { createHighlighter } = await import('shiki');
+
+    // 2. Initialize it as a singleton on the first run
+    if (!shikiInstance) {
+      shikiInstance = await createHighlighter({
+        themes: typeof theme === 'string' ? [theme] : [theme.light, theme.dark],
+        langs: options.langs || [language as BundledLanguage, 'javascript', 'typescript', 'bash', 'html', 'css'],
+      });
+    }
+
+    // 3. Load the language if it hasn't been loaded yet (catch-all for unexpected languages)
+    if (!shikiInstance.getLoadedLanguages().includes(language)) {
+      await shikiInstance.loadLanguage(language as BundledLanguage).catch(() => {});
+    }
+
+    const shikiOptions: any = {
+      lang: language,
+    };
+
+    if (typeof theme === 'string') {
+      shikiOptions.theme = theme;
+    } else {
+        shikiOptions.themes = theme;
+    }
+
+    return shikiInstance.codeToHtml(code, shikiOptions);
+  };
+}

package/src/engine.ts

@@ -0,0 +1,68 @@
+import { Marked } from 'marked';
+import { markedHighlight } from 'marked-highlight';
+import type { MarkdownConfig, MarkdownEngine, ParsedMarkdown } from './types';
+import { extractFrontmatter } from './frontmatter';
+import { extractHeadings } from './headings';
+import {
+  preprocessComponents,
+  copyCodeButtonRenderer,
+  headerAnchorsRenderer,
+} from './features';
+
+/** Configures and returns an isolated instance of the Markdown parsing engine. */
+export function createMDConfig(config: MarkdownConfig = {}): MarkdownEngine {
+  const markedInstance = new Marked({
+    gfm: true,
+  });
+
+  if (config.highlighter) {
+    markedInstance.use(
+      markedHighlight({
+        async: true,
+        highlight: async (code, lang) => {
+          if (!lang) return code;
+          return await (config.highlighter as any)(code, lang);
+        },
+      })
+    );
+  }
+
+  // Register built-in features using custom Marked renderers
+  const customRenderer: any = {};
+
+  if (config.features?.headerAnchors) {
+    customRenderer.heading = headerAnchorsRenderer;
+  }
+
+  if (config.features?.copyCodeButton) {
+    customRenderer.code = copyCodeButtonRenderer;
+  }
+
+  if (Object.keys(customRenderer).length > 0) {
+    markedInstance.use({ renderer: customRenderer });
+  }
+
+  return {
+    parse: async (rawString: string): Promise<ParsedMarkdown> => {
+      let { content, meta } = extractFrontmatter(rawString);
+      const headings = extractHeadings(content);
+
+      // Preprocess component blocks and custom tags before sending to Marked
+      content = await preprocessComponents(
+        content,
+        async (str) => await markedInstance.parse(str),
+        async (str) => await markedInstance.parseInline(str),
+        config.features,
+        config.components
+      );
+
+      const html = await markedInstance.parse(content);
+
+      return {
+        html,
+        meta,
+        headings,
+      };
+    },
+  };
+}