domma-cms 0.2.1 → 0.5.0

package/server/services/markdown.js

@@ -1,648 +1,1378 @@
-/**
- * Markdown Service
- * Parses frontmatter with gray-matter and renders Markdown to HTML with marked.
- */
-import matter from 'gray-matter';
-import {marked} from 'marked';
-import sanitizeHtml from 'sanitize-html';
-import {applyTransforms, getSanitizeExtensions, getShortcodeProcessors} from './hooks.js';
-
-// Configure marked for safe output
-marked.setOptions({
-    gfm: true,
-    breaks: false
-});
-
-/**
- * Parse key="value" or key='value' pairs from a shortcode attribute string.
- * @param {string} attrStr
- * @returns {object}
- */
-export function parseShortcodeAttrs(attrStr) {
-  const attrs = {};
-  for (const [, key, val] of attrStr.matchAll(/(\w+)=["']([^"']*)["']/g)) {
-    attrs[key] = val;
-  }
-  return attrs;
-}
-
-/**
- * Temporarily replace fenced code blocks and inline code spans with
- * non-matching placeholders so shortcode regexes cannot fire inside them.
- * Returns the scrubbed string and a restore function.
- *
- * @param {string} markdown
- * @returns {{ scrubbed: string, restore: (s: string) => string }}
- */
-export function scrubCodeRegions(markdown) {
-  const store = [];
-  const placeholder = (s) => {
-    const idx = store.length;
-    store.push(s);
-    return `\x02SC${idx}\x03`;
-  };
-
-  // Fenced code blocks (``` or ~~~, with optional language tag)
-  let scrubbed = markdown.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n\1[ \t]*$/gm, placeholder);
-  // Inline code spans (single or multiple backticks, non-greedy)
-  scrubbed = scrubbed.replace(/`+[^`\n]+`+/g, placeholder);
-
-  const restore = (s) => s.replace(/\x02SC(\d+)\x03/g, (_, i) => store[parseInt(i, 10)]);
-  return {scrubbed, restore};
-}
-
-/**
- * Run all plugin-registered shortcode handlers against the markdown string.
- * Self-closing ([name attrs /]) and wrapping ([name attrs]...[/name]) forms are both supported.
- * Code regions are scrubbed first so shortcodes inside fenced blocks are never processed.
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processPluginShortcodes(markdown) {
-  const processors = getShortcodeProcessors();
-  if (!processors.length) return markdown;
-
-  const {scrubbed, restore} = scrubCodeRegions(markdown);
-  let result = scrubbed;
-  const context = {parseShortcodeAttrs, scrubCodeRegions, marked, processCardBlocks, processGridBlocks, escapeAttr};
-
-  for (const {name, handler} of processors) {
-    // Self-closing: [name attrs /]
-    result = result.replace(
-      new RegExp(`\\[${name}([^\\]]*)\\s*\\/\\]`, 'gi'),
-      (_, attrStr) => handler(attrStr, null, context)
-    );
-    // Wrapping: [name attrs]...[/name]
-    result = result.replace(
-      new RegExp(`\\[${name}([^\\]]*)\\]([\\s\\S]*?)\\[\\/${name}\\]`, 'gi'),
-      (_, attrStr, body) => handler(attrStr, body, context)
-    );
-  }
-  return restore(result);
-}
-
-/**
- * Pre-process [row], [grid], and [col] shortcodes before running through marked.
- *
- * Uses Domma's native CSS Grid system — NOT the .col compatibility layer.
- *
- * Supported shortcodes:
- *
- *   [grid cols="N" gap="N"]
- *     [col span="N"] Content [/col]
- *   [/grid]
- *   → <div class="grid grid-cols-N gap-N"><div class="col-span-N">…</div></div>
- *
- *   [row gap="N"]
- *     [col] Content [/col]
- *   [/row]
- *   → <div class="row gap-N"><div>…</div></div>
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processGridBlocks(markdown) {
-  // Pass 1: [col span="N"]...[/col] → <div class="col-span-N">...</div>
-  let result = markdown.replace(
-    /\[col([^\]]*)\]([\s\S]*?)\[\/col\]/gi,
-    (_, attrStr, body) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const cls = attrs.span ? ` class="col-span-${attrs.span}"` : '';
-      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-      return `<div${cls}${id}>${marked.parse(processCardBlocks(body.trim()))}</div>`;
-    }
-  );
-
-  // Pass 2: [row gap="N" class="extra"]...[/row] → <div class="row ...">...</div>
-  result = result.replace(
-    /\[row([^\]]*)\]([\s\S]*?)\[\/row\]/gi,
-    (_, attrStr, inner) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const classes = ['row'];
-      if (attrs.gap) classes.push(`gap-${attrs.gap}`);
-      if (attrs.class) classes.push(attrs.class);
-      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-      return `<div class="${classes.join(' ')}"${id}>${inner}</div>\n`;
-    }
-  );
-
-  // Pass 3: [grid cols="N" gap="N"]...[/grid] → <div class="grid grid-cols-N ...">...</div>
-  result = result.replace(
-    /\[grid([^\]]*)\]([\s\S]*?)\[\/grid\]/gi,
-    (_, attrStr, inner) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const classes = ['grid'];
-      if (attrs.cols) classes.push(`grid-cols-${attrs.cols}`);
-      if (attrs.gap) classes.push(`gap-${attrs.gap}`);
-      if (attrs.class) classes.push(attrs.class);
-      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-      return `<div class="${classes.join(' ')}"${id}>${inner}</div>\n`;
-    }
-  );
-
-  return result;
-}
-
-/**
- * Escape a string for safe use inside an HTML double-quoted attribute value.
- * Prevents attribute-injection from shortcode attribute values.
- *
- * @param {string} str
- * @returns {string}
- */
-export function escapeAttr(str) {
-  return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
-}
-
-/**
- * Pre-process [card] shortcodes before running through marked.
- *
- * Syntax:
- *   [card title="Optional Title" collapsible="true"]
- *   Body content (supports Markdown).
- *   [/card]
- *
- * Supported attributes:
- *   title        - Card header title (omit for no header)
- *   collapsible  - "true" to make the card body toggle on header click
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processCardBlocks(markdown) {
-  return markdown.replace(
-    /\[card([^\]]*)\]([\s\S]*?)\[\/card\]/gi,
-    (_, attrStr, body) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const title = attrs.title?.trim() || '';
-      const collapsible = attrs.collapsible === 'true';
-
-      const titleHtml = title
-        ? `<div class="card-header"><h2>${title}</h2></div>`
-        : '';
-      const bodyHtml = marked.parse(body.trim());
-      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-      const extra = collapsible ? ' data-collapsible="true"' : '';
-      return `<div class="card mb-4"${extra}${id}>${titleHtml}<div class="card-body">${bodyHtml}</div></div>\n`;
-    }
-  );
-}
-
-/**
- * Pre-process [tabs] / [tab] shortcodes before running through marked.
- *
- * Syntax:
- *   [tabs id="optional" style="pills"]
- *   [tab title="First"]Content[/tab]
- *   [tab title="Second"]Content[/tab]
- *   [/tabs]
- *
- * Supported attributes on [tabs]:
- *   style  - "pills" for pill-style nav (default: standard underline)
- *   id     - optional id on the wrapper
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processTabsBlocks(markdown) {
-  const {scrubbed, restore} = scrubCodeRegions(markdown);
-  let counter = 0;
-  const processed = scrubbed.replace(
-    /\[tabs([^\]]*)\]([\s\S]*?)\[\/tabs\]/gi,
-    (_, attrStr, body) => {
-      counter++;
-      const prefix = `dm-tab-${counter}`;
-      const attrs = parseShortcodeAttrs(attrStr);
-      const pillsClass = attrs.style === 'pills' ? ' tabs-pills' : '';
-      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-
-      // Parse inner [tab title="..."] items
-      let tabIdx = 0;
-      const items = [];
-      body.replace(/\[tab([^\]]*)\]([\s\S]*?)\[\/tab\]/gi, (__, tabAttr, tabBody) => {
-        tabIdx++;
-        const tabAttrs = parseShortcodeAttrs(tabAttr);
-        const title = tabAttrs.title || `Tab ${tabIdx}`;
-        const paneId = `${prefix}-${tabIdx}`;
-        const bodyHtml = marked.parse(processCardBlocks(processGridBlocks(tabBody.trim())));
-        items.push({title, paneId, bodyHtml, first: tabIdx === 1});
-      });
-
-      if (!items.length) return '';
-
-      const navItems = items.map(t =>
-        `<button class="tab-item${t.first ? ' active' : ''}">${escapeAttr(t.title)}</button>`
-      ).join('\n    ');
-      const panes = items.map(t =>
-        `<div class="tab-panel${t.first ? ' active' : ''}">${t.bodyHtml}</div>`
-      ).join('\n    ');
-
-      return (
-        `<div class="tabs${pillsClass}"${idAttr}>\n` +
-        `  <div class="tab-list">\n    ${navItems}\n  </div>\n` +
-        `  <div class="tab-content">\n    ${panes}\n  </div>\n` +
-        `</div>\n`
-      );
-    }
-  );
-  return restore(processed);
-}
-
-/**
- * Pre-process [accordion] / [item] shortcodes before running through marked.
- *
- * Syntax:
- *   [accordion multiple="true" id="optional"]
- *   [item title="Section 1"]Content[/item]
- *   [item title="Section 2"]Content[/item]
- *   [/accordion]
- *
- * Supported attributes on [accordion]:
- *   multiple - "true" to allow multiple panels open simultaneously
- *   id       - optional id on the wrapper
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processAccordionBlocks(markdown) {
-  const {scrubbed, restore} = scrubCodeRegions(markdown);
-  const processed = scrubbed.replace(
-    /\[accordion([^\]]*)\]([\s\S]*?)\[\/accordion\]/gi,
-    (_, attrStr, body) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const multiAttr = attrs.multiple === 'true' ? ' data-multi="true"' : '';
-      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-
-      let items = '';
-      body.replace(/\[item([^\]]*)\]([\s\S]*?)\[\/item\]/gi, (__, itemAttr, itemBody) => {
-        const itemAttrs = parseShortcodeAttrs(itemAttr);
-        const title = itemAttrs.title || 'Item';
-        const bodyHtml = marked.parse(processCardBlocks(processGridBlocks(itemBody.trim())));
-        items += (
-          `<div class="accordion-item">\n` +
-          `  <h3 class="accordion-header"><button class="accordion-button" type="button">${escapeAttr(title)}` +
-          `<span class="accordion-icon" data-icon="chevron-down"></span></button></h3>\n` +
-          `  <div class="accordion-body"><div class="accordion-content">${bodyHtml}</div></div>\n` +
-          `</div>\n`
-        );
-      });
-
-      return `<div class="accordion"${idAttr}${multiAttr}>\n${items}</div>\n`;
-    }
-  );
-  return restore(processed);
-}
-
-/**
- * Pre-process [carousel] / [slide] shortcodes before running through marked.
- *
- * Syntax:
- *   [carousel autoplay="true" interval="5000" loop="true" animation="slide" id="optional"]
- *   [slide title="Optional" image="/media/photo.jpg"]Body content[/slide]
- *   [slide]Text-only slide content[/slide]
- *   [/carousel]
- *
- * Supported attributes on [carousel]:
- *   autoplay  - "true" to auto-advance slides
- *   interval  - milliseconds between slides (default 5000)
- *   loop      - "false" to disable loop (default true)
- *   animation - "fade" or "slide" (default slide)
- *   id        - optional id on the wrapper
- *
- * Supported attributes on [slide]:
- *   image - URL of a background/header image
- *   title - slide heading text
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processCarouselBlocks(markdown) {
-  const {scrubbed, restore} = scrubCodeRegions(markdown);
-  const processed = scrubbed.replace(
-    /\[carousel([^\]]*)\]([\s\S]*?)\[\/carousel\]/gi,
-    (_, attrStr, body) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const dataAttrs = [
-        attrs.autoplay ? ` data-autoplay="${escapeAttr(attrs.autoplay)}"` : '',
-        attrs.interval ? ` data-interval="${escapeAttr(attrs.interval)}"` : '',
-        attrs.loop ? ` data-loop="${escapeAttr(attrs.loop)}"` : '',
-        attrs.animation ? ` data-animation="${escapeAttr(attrs.animation)}"` : ''
-      ].join('');
-      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-
-      let slides = '';
-      body.replace(/\[slide([^\]]*)\]([\s\S]*?)\[\/slide\]/gi, (__, slideAttr, slideBody) => {
-        const slideAttrs = parseShortcodeAttrs(slideAttr);
-        let inner = '';
-        if (slideAttrs.image) {
-          inner += `<img src="${escapeAttr(slideAttrs.image)}" alt="${escapeAttr(slideAttrs.title || '')}">\n`;
-        }
-        const contentHtml = marked.parse(processCardBlocks(processGridBlocks(slideBody.trim())));
-        if (slideAttrs.title || slideBody.trim()) {
-          inner += `<div class="carousel-slide-content">`;
-          if (slideAttrs.title) inner += `<h2 class="carousel-slide-title">${escapeAttr(slideAttrs.title)}</h2>`;
-          if (slideBody.trim()) inner += `<div class="carousel-slide-description">${contentHtml}</div>`;
-          inner += `</div>`;
-        }
-        slides += `<div class="carousel-slide">${inner}</div>\n`;
-      });
-
-      return `<div class="carousel"${idAttr}${dataAttrs}><div class="carousel-track">${slides}</div></div>\n`;
-    }
-  );
-  return restore(processed);
-}
-
-/**
- * Pre-process [countdown] self-closing shortcodes before running through marked.
- *
- * Syntax:
- *   [countdown to="2026-12-31" format="DD:HH:mm:ss" /]
- *   [countdown duration="300" format="mm:ss" /]
- *
- * Supported attributes:
- *   to       - ISO date string for a fixed target date
- *   duration - seconds to count down from (used if to is absent)
- *   format   - display format: "mm:ss", "HH:mm:ss", "DD:HH:mm:ss" (default mm:ss)
- *   id       - optional id on the element
- *
- * Client-side site.js initialises .dm-countdown elements via E.timer().
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processCountdownBlocks(markdown) {
-  return markdown.replace(
-    /\[countdown([^\]]*?)\/\]/gi,
-    (_, attrStr) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const dataAttrs = [
-        attrs.to ? ` data-to="${escapeAttr(attrs.to)}"` : '',
-        attrs.duration ? ` data-duration="${escapeAttr(attrs.duration)}"` : '',
-        attrs.format ? ` data-format="${escapeAttr(attrs.format)}"` : ''
-      ].join('');
-      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-      return `<div class="dm-countdown"${idAttr}${dataAttrs}></div>`;
-    }
-  );
-}
-
-/**
- * Pre-process [table] shortcodes before running through marked.
- *
- * Wraps a GFM Markdown table with Domma CSS classes and a responsive container.
- *
- * Syntax:
- *   [table striped="true" bordered="true" compact="true" caption="Sales Data"]
- *   | Product | Price |
- *   | ------- | ----: |
- *   | Widget  | $9.99 |
- *   [/table]
- *
- * Supported attributes:
- *   striped  - "true" → .table-striped
- *   bordered - "true" → .table-bordered
- *   compact  - "true" → .table-compact
- *   caption  - text inserted as <caption>
- *   class    - extra classes appended to .table
- *   id       - id attribute on the <table>
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processTableBlocks(markdown) {
-  return markdown.replace(
-    /\[table([^\]]*)\]([\s\S]*?)\[\/table\]/gi,
-    (_, attrStr, body) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const classes = ['table'];
-      if (attrs.striped === 'true') classes.push('table-striped');
-      if (attrs.bordered === 'true') classes.push('table-bordered');
-      if (attrs.compact === 'true') classes.push('table-compact');
-      if (attrs.class) classes.push(attrs.class);
-
-      const caption = attrs.caption
-        ? `<caption>${escapeAttr(attrs.caption)}</caption>`
-        : '';
-      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-
-      let tableHtml = marked.parse(body.trim());
-
-      tableHtml = tableHtml.replace(
-        '<table>',
-        `<table class="${classes.join(' ')}"${idAttr}>${caption}`
-      );
-
-      return `<div class="table-responsive">${tableHtml}</div>\n`;
-    }
-  );
-}
-
-/**
- * Pre-process [hero] shortcodes before running through marked.
- *
- * Syntax:
- *   [hero title="Welcome" tagline="Build something great" size="lg" variant="gradient-blue"]
- *   Optional body content with **Markdown** support.
- *   [/hero]
- *
- * Supported attributes:
- *   title   - Hero heading (.hero-title)
- *   tagline - Subtitle text (.hero-subtitle)
- *   size    - "sm", "lg", "full" → .hero-sm / .hero-lg / .hero-full
- *   variant - "dark", "primary", "gradient-blue", "gradient-purple",
- *             "gradient-sunset", "gradient-ocean" → .hero-{variant}
- *   image   - URL for background-image + adds .hero-cover
- *   overlay - "light", "dark", "darker", "gradient", "gradient-reverse" → .hero-overlay-{overlay}
- *   align   - "center" (default) or "left" → .hero-center / .hero-left
- *   class   - Extra classes appended to .hero
- *   id      - Element id attribute
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processHeroBlocks(markdown) {
-  return markdown.replace(
-    /\[hero([^\]]*)\]([\s\S]*?)\[\/hero\]/gi,
-    (_, attrStr, body) => {
-      const attrs = parseShortcodeAttrs(attrStr);
-      const title = attrs.title || '';
-      const tagline = attrs.tagline || '';
-      const size = attrs.size || '';
-      const variant = attrs.variant || '';
-      const image = attrs.image || '';
-      const overlay = attrs.overlay || '';
-      const align = attrs.align || 'center';
-      const fullwidth = attrs.fullwidth === 'true';
-      const cls = attrs.class || '';
-      const id = attrs.id || '';
-
-      const classes = ['hero'];
-      if (size) classes.push(`hero-${size}`);
-      if (variant) classes.push(`hero-${variant}`);
-      if (align) classes.push(`hero-${align}`);
-      if (image) classes.push('hero-cover');
-      if (overlay) classes.push(`hero-overlay-${overlay}`);
-      if (fullwidth) classes.push('hero-breakout');
-      if (cls) classes.push(cls);
-
-      const style = image ? ` style="background-image:url('${escapeAttr(image)}')"` : '';
-      const idAttr = id ? ` id="${escapeAttr(id)}"` : '';
-
-      const processedBody = processCardBlocks(processGridBlocks(body.trim()));
-
-      let inner = '<div class="hero-content">';
-      if (title) inner += `<h1 class="hero-title hero-title-responsive">${escapeAttr(title)}</h1>`;
-      if (tagline) inner += `<p class="hero-subtitle hero-subtitle-responsive">${escapeAttr(tagline)}</p>`;
-      if (processedBody) inner += `<div class="hero-body">${marked.parse(processedBody)}</div>`;
-      inner += '</div>';
-
-      return `<div class="${classes.join(' ')}"${idAttr}${style}>${inner}</div>\n`;
-    }
-  );
-}
-
-/**
- * Pre-process [slideover] shortcodes before running through marked.
- *
- * Syntax:
- *   [slideover title="More Info" trigger="Read more" size="md" position="right"]
- *   Markdown body here.
- *   [/slideover]
- *
- * Outputs a trigger button and a hidden content div with data attributes.
- * Client-side site.js wires up the click handler to open a Domma slideover.
- * Attribute values are HTML-escaped to prevent injection.
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processSlideoverBlocks(markdown) {
-  const {scrubbed, restore} = scrubCodeRegions(markdown);
-  let counter = 0;
-  const processed = scrubbed.replace(
-    /\[slideover([^\]]*)\]([\s\S]*?)\[\/slideover\]/gi,
-    (_, attrStr, body) => {
-      counter++;
-      const id = `dm-so-${counter}`;
-      const attrs = parseShortcodeAttrs(attrStr);
-      const title = escapeAttr(attrs.title || '');
-      const trigger = escapeAttr(attrs.trigger || 'Open');
-      const size = escapeAttr(attrs.size || 'md');
-      const position = escapeAttr(attrs.position || 'right');
-      const bodyHtml = marked.parse(processCardBlocks(processGridBlocks(body.trim())));
-      return (
-        `<button class="btn btn-link dm-so-trigger" data-so-target="${id}">${trigger}</button>\n` +
-        `<div class="dm-so-content" id="${id}" style="display:none" ` +
-        `data-so-title="${title}" data-so-size="${size}" data-so-position="${position}">${bodyHtml}</div>\n`
-      );
-    }
-  );
-  return restore(processed);
-}
-
-/**
- * Pre-process [dconfig] shortcodes before running through marked.
- *
- * Extracts JSON config blocks and base64-encodes them into hidden divs.
- * Multiple blocks on one page are supported and merged client-side.
- * Invalid JSON blocks are silently dropped (no render output).
- *
- * Syntax:
- *   [dconfig]
- *   { "#btn": { "events": { "click": { "target": "#panel", "toggleClass": "hidden" } } } }
- *   [/dconfig]
- *
- * @param {string} markdown
- * @returns {string}
- */
-function processDConfigBlocks(markdown) {
-  const {scrubbed, restore} = scrubCodeRegions(markdown);
-  const processed = scrubbed.replace(
-    /\[dconfig\]([\s\S]*?)\[\/dconfig\]/gi,
-    (_, jsonStr) => {
-      try {
-        JSON.parse(jsonStr.trim()); // validate before encoding
-        const encoded = Buffer.from(jsonStr.trim(), 'utf8').toString('base64');
-        return `<div class="dm-page-config" style="display:none" data-config="${encoded}"></div>\n`;
-      } catch {
-        return ''; // invalid JSON — drop silently
-      }
-    }
-  );
-  return restore(processed);
-}
-
-/**
- * Parse a Markdown file string into frontmatter data and rendered HTML.
- *
- * @param {string} raw - Raw file content (frontmatter + Markdown body)
- * @returns {{ data: object, content: string, html: string }}
- */
-export function parseMarkdown(raw) {
-  const {data, content} = matter(raw);
-  const extensions = getSanitizeExtensions();
-
-  // Pipeline:
-  // beforeParse → dconfig → plugin shortcodes → tabs → accordion → carousel → countdown
-  //   → hero → grid → card → slideover → marked → sanitize → afterParse
-  const preprocessed = applyTransforms('markdown:beforeParse', content);
-  const withDconfig = processDConfigBlocks(preprocessed);
-  const withPluginShortcodes = processPluginShortcodes(withDconfig);
-  const withTabs = processTabsBlocks(withPluginShortcodes);
-  const withAccordion = processAccordionBlocks(withTabs);
-  const withCarousel = processCarouselBlocks(withAccordion);
-  const withCountdown = processCountdownBlocks(withCarousel);
-  const withHero = processHeroBlocks(withCountdown);
-  const withTable = processTableBlocks(withHero);
-  const withGrid = processGridBlocks(withTable);
-  const withCard = processCardBlocks(withGrid);
-  const withSlideover = processSlideoverBlocks(withCard);
-  const rendered = marked.parse(withSlideover);
-
-  const sanitized = sanitizeHtml(rendered, {
-    allowedTags: sanitizeHtml.defaults.allowedTags.concat([
-      'img', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
-      'form', 'input', 'textarea', 'select', 'option', 'optgroup',
-      'button', 'label', 'fieldset', 'legend',
-      ...extensions.tags
-    ]),
-    allowedAttributes: {
-      ...sanitizeHtml.defaults.allowedAttributes,
-      '*': ['class', 'id', 'style', 'data-*'],
-      img: ['src', 'alt', 'title', 'width', 'height', 'loading'],
-      form: ['action', 'method'],
-      input: ['type', 'name', 'placeholder', 'value', 'required', 'disabled',
-        'readonly', 'min', 'max', 'step', 'pattern', 'maxlength',
-        'minlength', 'checked', 'autocomplete'],
-      textarea: ['name', 'placeholder', 'rows', 'cols', 'required',
-        'disabled', 'readonly', 'maxlength'],
-      select: ['name', 'required', 'disabled', 'multiple'],
-      option: ['value', 'selected', 'disabled'],
-      optgroup: ['label', 'disabled'],
-      button: ['type', 'disabled'],
-      label: ['for'],
-      fieldset: ['disabled'],
-      ...extensions.attributes
-    }
-  });
-
-  const html = applyTransforms('markdown:afterParse', sanitized);
-  return {data, content, html};
-}
-
-/**
- * Serialise a page object back to a Markdown file string.
- *
- * @param {object} frontmatter - Page metadata fields
- * @param {string} body - Markdown body
- * @returns {string}
- */
-export function serialiseMarkdown(frontmatter, body) {
-    return matter.stringify(body || '', frontmatter);
-}
+/**
+ * Markdown Service
+ * Parses frontmatter with gray-matter and renders Markdown to HTML with marked.
+ */
+import matter from 'gray-matter';
+import {marked} from 'marked';
+import sanitizeHtml from 'sanitize-html';
+import {readFile} from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {applyTransforms, getSanitizeExtensions, getShortcodeProcessors} from './hooks.js';
+import {getConfig} from '../config.js';
+import {getCollection, listEntries} from './collections.js';
+
+const __dirname_md = path.dirname(fileURLToPath(import.meta.url));
+const BLOCKS_DIR = path.resolve(__dirname_md, '../../content/blocks');
+
+// Configure marked for safe output
+marked.setOptions({
+    gfm: true,
+    breaks: false
+});
+
+// ---------------------------------------------------------------------------
+// Collection shortcode helpers
+// ---------------------------------------------------------------------------
+
+function escapeHtmlText(str) {
+    return String(str ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+
+function sortEntries(entries, sort, order) {
+    const dir = order === 'asc' ? 1 : -1;
+    return [...entries].sort((a, b) => {
+        const av = sort === 'createdAt' ? (a.meta?.createdAt || '') : (a.data?.[sort] ?? '');
+        const bv = sort === 'createdAt' ? (b.meta?.createdAt || '') : (b.data?.[sort] ?? '');
+        return av < bv ? -dir : av > bv ? dir : 0;
+    });
+}
+
+/**
+ * Load a block template by name from content/blocks/{name}.html.
+ * Throws if the file does not exist.
+ *
+ * @param {string} blockName
+ * @returns {Promise<string>}
+ */
+async function loadBlockTemplate(blockName) {
+    const safe = path.basename(blockName).replace(/[^a-z0-9-]/g, '');
+    return readFile(path.join(BLOCKS_DIR, `${safe}.html`), 'utf8');
+}
+
+/**
+ * Render collection entries using a reusable HTML block template.
+ * Replaces {{fieldName}}, {{_id}}, {{_createdAt}}, {{_updatedAt}} placeholders.
+ *
+ * @param {Array}  entries       - Collection entries with { id, data, meta }
+ * @param {string} blockTemplate - Raw HTML template with {{placeholders}}
+ * @param {string} emptyMsg      - Message to show when entries is empty
+ * @param {object|null} ctaOpts  - Optional CTA button options
+ * @returns {string}
+ */
+function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts) {
+    if (!entries.length) {
+        return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
+    }
+
+    const items = entries.map(e => {
+        let html = blockTemplate.replace(/\{\{([\w_]+)\}\}/g, (_, key) => {
+            if (key === '_id') return escapeHtmlText(e.id ?? '');
+            if (key === '_createdAt') return escapeHtmlText(e.meta?.createdAt ?? '');
+            if (key === '_updatedAt') return escapeHtmlText(e.meta?.updatedAt ?? '');
+            return escapeHtmlText(e.data?.[key] ?? '');
+        });
+
+        if (ctaOpts) {
+            const ctaStyle = escapeAttr(ctaOpts.style || 'primary');
+            let btnCls = `btn btn-${ctaStyle} dm-cta-trigger`;
+            let btnData = `data-action="${escapeAttr(ctaOpts.action)}" data-entry="${escapeAttr(e.id || '')}"`;
+            if (ctaOpts.confirm) btnData += ` data-confirm="${escapeAttr(ctaOpts.confirm)}"`;
+            const iconHtml = ctaOpts.icon ? `<span data-icon="${escapeAttr(ctaOpts.icon)}"></span> ` : '';
+            html += `\n<button class="${btnCls}" ${btnData}>${iconHtml}${escapeHtmlText(ctaOpts.label || 'Run')}</button>`;
+        }
+        return html;
+    });
+
+    return `<div class="dm-collection-display dm-collection-blocks">\n${items.join('\n')}\n</div>`;
+}
+
+function renderCollectionTable(slug, entries, visibleFields, attrs, ctaOpts) {
+    const columns = visibleFields.map(f => ({key: f.name, title: f.label || f.name}));
+    const rows = entries.map(e => {
+        const row = {};
+        visibleFields.forEach(f => {
+            row[f.name] = e.data?.[f.name] ?? '';
+        });
+        if (ctaOpts) row._entryId = e.id || '';
+        return row;
+    });
+    if (ctaOpts) columns.push({key: '_cta', title: ''});
+    const tableOpts = {
+        columns,
+        rows,
+        search: attrs.search !== 'false',
+        sortable: attrs.sortable !== 'false',
+        exportable: attrs.exportable === 'true',
+        pageSize: parseInt(attrs['page-size'], 10) || 25,
+        empty: attrs.empty || 'No entries found'
+    };
+    if (ctaOpts) tableOpts.ctaConfig = ctaOpts;
+    const payload = Buffer.from(JSON.stringify(tableOpts)).toString('base64');
+    return `<div class="dm-collection-display" data-collection-table data-slug="${escapeAttr(slug)}" data-payload="${payload}"></div>`;
+}
+
+function renderCollectionCards(entries, visibleFields, titleField, columns, emptyMsg, ctaOpts) {
+    const cols = ['2', '3', '4'].includes(String(columns)) ? columns : '3';
+    if (!entries.length) {
+        return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
+    }
+    const cards = entries.map(e => {
+        const title = titleField ? escapeHtmlText(e.data?.[titleField] ?? '') : '';
+        const body  = visibleFields
+            .filter(f => f.name !== titleField)
+            .map(f => {
+                const val = escapeHtmlText(e.data?.[f.name] ?? '');
+                return val ? `<p><strong>${escapeHtmlText(f.label || f.name)}:</strong> ${val}</p>` : '';
+            }).join('');
+        let footer = '';
+        if (ctaOpts) {
+            const ctaStyle = escapeAttr(ctaOpts.style || 'primary');
+            let btnCls = `btn btn-${ctaStyle} dm-cta-trigger`;
+            let btnData = `data-action="${escapeAttr(ctaOpts.action)}" data-entry="${escapeAttr(e.id || '')}"`;
+            if (ctaOpts.confirm) btnData += ` data-confirm="${escapeAttr(ctaOpts.confirm)}"`;
+            const iconHtml = ctaOpts.icon ? `<span data-icon="${escapeAttr(ctaOpts.icon)}"></span> ` : '';
+            footer = `<div class="card-footer"><button class="${btnCls}" ${btnData}>${iconHtml}${escapeHtmlText(ctaOpts.label || 'Run')}</button></div>`;
+        }
+        return `<div class="card">${title ? `<div class="card-header">${title}</div>` : ''}<div class="card-body">${body || '&nbsp;'}</div>${footer}</div>`;
+    }).join('\n');
+    return `<div class="dm-collection-display grid grid-cols-${cols} gap-4">\n${cards}\n</div>`;
+}
+
+function renderCollectionList(entries, visibleFields, titleField, emptyMsg, ctaOpts) {
+    if (!entries.length) {
+        return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
+    }
+    const items = entries.map(e => {
+        const title = titleField ? escapeHtmlText(e.data?.[titleField] ?? '') : '';
+        const rest  = visibleFields
+            .filter(f => f.name !== titleField)
+            .map(f => {
+                const val = escapeHtmlText(e.data?.[f.name] ?? '');
+                return val ? `<p>${val}</p>` : '';
+            }).join('');
+        let ctaHtml = '';
+        if (ctaOpts) {
+            const ctaStyle = escapeAttr(ctaOpts.style || 'primary');
+            let btnCls = `btn btn-${ctaStyle} dm-cta-trigger`;
+            let btnData = `data-action="${escapeAttr(ctaOpts.action)}" data-entry="${escapeAttr(e.id || '')}"`;
+            if (ctaOpts.confirm) btnData += ` data-confirm="${escapeAttr(ctaOpts.confirm)}"`;
+            const iconHtml = ctaOpts.icon ? `<span data-icon="${escapeAttr(ctaOpts.icon)}"></span> ` : '';
+            ctaHtml = `<button class="${btnCls}" ${btnData}>${iconHtml}${escapeHtmlText(ctaOpts.label || 'Run')}</button>`;
+        }
+        return `<div class="dm-collection-list-item">${title ? `<strong>${title}</strong>` : ''}${rest}${ctaHtml}</div>`;
+    }).join('\n');
+    return `<div class="dm-collection-display dm-collection-list">\n${items}\n</div>`;
+}
+
+/**
+ * Process [view slug="..." display="table|cards|list" /] shortcodes.
+ * Executes the View's aggregation pipeline and renders results using the
+ * same render functions as [collection].
+ *
+ * @param {string} markdown
+ * @returns {Promise<string>}
+ */
+async function processViewBlocks(markdown) {
+    const {scrubbed, restore} = scrubCodeRegions(markdown);
+    const pattern = /\[view([^\]]*?)\/\]/gi;
+    const matches = [...scrubbed.matchAll(pattern)];
+    if (!matches.length) return markdown;
+
+    let result = scrubbed;
+
+    for (const match of matches) {
+        const [fullMatch, attrStr] = match;
+        const attrs     = parseShortcodeAttrs(attrStr);
+        const slug      = attrs.slug || '';
+        if (!slug) {
+            result = result.replace(fullMatch, '');
+            continue;
+        }
+
+        const displayAttr = attrs.display || '';
+        const emptyMsg   = attrs.empty      || 'No results found';
+        const titleField = attrs['title-field'] || '';
+        const columns    = attrs.columns    || '3';
+        const limitAttr  = parseInt(attrs.limit, 10) || 25;
+        const fieldFilter = attrs.fields ? attrs.fields.split(',').map(f => f.trim()).filter(Boolean) : null;
+
+        const ctaOpts = attrs.action ? {
+            action: attrs.action,
+            label: attrs['cta-label'] || 'Run',
+            style: attrs['cta-style'] || 'primary',
+            icon: attrs['cta-icon'] || '',
+            confirm: attrs['cta-confirm'] || ''
+        } : null;
+
+        let replacement = `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
+
+        try {
+            const {executeView, getView} = await import('./views.js');
+            const [{results}, viewConfig] = await Promise.all([
+                executeView(slug, {page: 1, limit: limitAttr}),
+                getView(slug).catch(() => null)
+            ]);
+
+            // Map MongoDB docs to { id, data } shape. MongoAdapter docs have a top-level id field.
+            const entries = results.map(doc => ({id: doc.id || '', data: doc.data || doc}));
+
+            // Derive visible fields from attr filter or first entry's data keys
+            let fields;
+            if (fieldFilter?.length) {
+                fields = fieldFilter.map(name => ({ name, label: name }));
+            } else if (entries.length) {
+                fields = Object.keys(entries[0].data || {})
+                    .filter(k => !['_id', 'id', 'meta'].includes(k))
+                    .map(k => ({name: k, label: k}));
+            } else {
+                fields = [];
+            }
+
+            const display = displayAttr || viewConfig?.display?.mode || 'table';
+
+            if (display === 'cards') {
+                replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts);
+            } else if (display === 'list') {
+                replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts);
+            } else if (display === 'block') {
+                const blockName = attrs.block || viewConfig?.display?.block || '';
+                if (blockName) {
+                    try {
+                        const tpl = await loadBlockTemplate(blockName);
+                        replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts);
+                    } catch {
+                        replacement = `<div class="dm-collection-display dm-collection-empty"><p>Block template &ldquo;${escapeHtmlText(blockName)}&rdquo; not found.</p></div>`;
+                    }
+                }
+            } else {
+                replacement = renderCollectionTable(`view:${slug}`, entries, fields, attrs, ctaOpts);
+            }
+        } catch {
+            // View not found, MongoDB not configured, or pipeline error — show empty state
+        }
+
+        result = result.replace(fullMatch, replacement);
+    }
+
+    return restore(result);
+}
+
+/**
+ * Process [collection slug="..." display="..." /] shortcodes.
+ * Fetches entries server-side and renders static HTML.
+ *
+ * @param {string} markdown
+ * @returns {Promise<string>}
+ */
+async function processCollectionBlocks(markdown) {
+    const {scrubbed, restore} = scrubCodeRegions(markdown);
+    // Find all [collection ...] shortcodes
+    const pattern = /\[collection([^\]]*?)\/\]/gi;
+    const matches = [...scrubbed.matchAll(pattern)];
+    if (!matches.length) return markdown;
+
+    let result = scrubbed;
+
+    for (const match of matches) {
+        const [fullMatch, attrStr] = match;
+        const attrs = parseShortcodeAttrs(attrStr);
+        const slug  = attrs.slug || '';
+        if (!slug) {
+            result = result.replace(fullMatch, '');
+            continue;
+        }
+
+        const display    = attrs.display || 'table';
+        const limitAttr  = parseInt(attrs.limit, 10) || 0;
+        const sort       = attrs.sort  || 'createdAt';
+        const order      = attrs.order || 'desc';
+        const titleField = attrs['title-field'] || '';
+        const columns    = attrs.columns || '3';
+        const emptyMsg   = attrs.empty  || 'No entries found';
+        const fieldFilter = attrs.fields ? attrs.fields.split(',').map(f => f.trim()).filter(Boolean) : null;
+        const ctaAction  = attrs.cta || '';
+        const ctaOpts    = ctaAction ? {
+            action:  ctaAction,
+            label:   attrs['cta-label']   || 'Run',
+            icon:    attrs['cta-icon']    || '',
+            style:   attrs['cta-style']   || 'primary',
+            confirm: attrs['cta-confirm'] || ''
+        } : null;
+
+        let replacement = `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
+
+        try {
+            const schema  = await getCollection(slug);
+            if (!schema) throw new Error('not found');
+
+            let {entries} = await listEntries(slug);
+            entries = sortEntries(entries, sort, order);
+            if (limitAttr > 0) entries = entries.slice(0, limitAttr);
+
+            // Determine visible fields from schema (optionally filtered)
+            let fields = schema.fields || [];
+            if (fieldFilter?.length) {
+                fields = fieldFilter.map(name => fields.find(f => f.name === name) || { name, label: name });
+            }
+            if (!fields.length && entries.length) {
+                // No schema fields — derive from first entry's data keys
+                fields = Object.keys(entries[0].data || {}).map(k => ({ name: k, label: k }));
+            }
+
+            if (display === 'cards') {
+                replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts);
+            } else if (display === 'list') {
+                replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts);
+            } else if (display === 'block') {
+                const blockName = attrs.block || '';
+                if (blockName) {
+                    try {
+                        const tpl = await loadBlockTemplate(blockName);
+                        replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts);
+                    } catch {
+                        replacement = `<div class="dm-collection-display dm-collection-empty"><p>Block template &ldquo;${escapeHtmlText(blockName)}&rdquo; not found.</p></div>`;
+                    }
+                }
+            } else {
+                replacement = renderCollectionTable(slug, entries, fields, attrs, ctaOpts);
+            }
+        } catch {
+            // Collection not found or read error — show empty message
+        }
+
+        result = result.replace(fullMatch, replacement);
+    }
+
+    return restore(result);
+}
+
+/**
+ * Parse key="value" or key='value' pairs from a shortcode attribute string.
+ * @param {string} attrStr
+ * @returns {object}
+ */
+export function parseShortcodeAttrs(attrStr) {
+  const attrs = {};
+  // Pass 1: quoted key="value" or key='value' pairs
+  for (const [, key, val] of attrStr.matchAll(/([\w-]+)=["']([^"']*)["']/g)) {
+    attrs[key] = val;
+  }
+  // Pass 2: standalone flag attributes (no value) — blank out key=value matches first
+  const stripped = attrStr.replace(/([\w-]+)=["'][^"']*["']/g, m => ' '.repeat(m.length));
+  for (const [, key] of stripped.matchAll(/\b([\w-]+)\b/g)) {
+    if (!(key in attrs)) attrs[key] = true;
+  }
+  return attrs;
+}
+
+/**
+ * Temporarily replace fenced code blocks and inline code spans with
+ * non-matching placeholders so shortcode regexes cannot fire inside them.
+ * Returns the scrubbed string and a restore function.
+ *
+ * @param {string} markdown
+ * @returns {{ scrubbed: string, restore: (s: string) => string }}
+ */
+export function scrubCodeRegions(markdown) {
+  const store = [];
+  const placeholder = (s) => {
+    const idx = store.length;
+    store.push(s);
+    return `\x02SC${idx}\x03`;
+  };
+
+    // HTML <pre><code>...</code></pre> blocks (rendered by earlier marked.parse calls inside accordion/carousel etc.)
+    let scrubbed = markdown.replace(/<pre\b[^>]*>[\s\S]*?<\/pre>/gi, placeholder);
+  // Fenced code blocks (``` or ~~~, with optional language tag)
+    scrubbed = scrubbed.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n\1[ \t]*$/gm, placeholder);
+  // Inline code spans (single or multiple backticks, non-greedy)
+  scrubbed = scrubbed.replace(/`+[^`\n]+`+/g, placeholder);
+
+  const restore = (s) => s.replace(/\x02SC(\d+)\x03/g, (_, i) => store[parseInt(i, 10)]);
+  return {scrubbed, restore};
+}
+
+/**
+ * Run all plugin-registered shortcode handlers against the markdown string.
+ * Self-closing ([name attrs /]) and wrapping ([name attrs]...[/name]) forms are both supported.
+ * Code regions are scrubbed first so shortcodes inside fenced blocks are never processed.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processPluginShortcodes(markdown) {
+  const processors = getShortcodeProcessors();
+  if (!processors.length) return markdown;
+
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  let result = scrubbed;
+  const context = {parseShortcodeAttrs, scrubCodeRegions, marked, processCardBlocks, processGridBlocks, escapeAttr};
+
+  for (const {name, handler} of processors) {
+    // Self-closing: [name attrs /]
+    result = result.replace(
+      new RegExp(`\\[${name}([^\\]]*)\\s*\\/\\]`, 'gi'),
+      (_, attrStr) => handler(attrStr, null, context)
+    );
+    // Wrapping: [name attrs]...[/name]
+    result = result.replace(
+      new RegExp(`\\[${name}([^\\]]*)\\]([\\s\\S]*?)\\[\\/${name}\\]`, 'gi'),
+      (_, attrStr, body) => handler(attrStr, body, context)
+    );
+  }
+  return restore(result);
+}
+
+/**
+ * Pre-process [row], [grid], and [col] shortcodes before running through marked.
+ *
+ * Uses Domma's native CSS Grid system — NOT the .col compatibility layer.
+ *
+ * Supported shortcodes:
+ *
+ *   [grid cols="N" gap="N"]
+ *     [col span="N"] Content [/col]
+ *   [/grid]
+ *   → <div class="grid grid-cols-N gap-N"><div class="col-span-N">…</div></div>
+ *
+ *   [row gap="N"]
+ *     [col] Content [/col]
+ *   [/row]
+ *   → <div class="row gap-N"><div>…</div></div>
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processGridBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  // Pass 1: [col span="N"]...[/col] → <div class="col-span-N">...</div>
+  let result = scrubbed.replace(
+    /\[col([^\]]*)\]([\s\S]*?)\[\/col\]/gi,
+    (_, attrStr, body) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const cls = attrs.span ? ` class="col-span-${attrs.span}"` : '';
+      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+      return `<div${cls}${id}>${marked.parse(processCardBlocks(body.trim()))}</div>`;
+    }
+  );
+
+  // Pass 2: [row gap="N" class="extra"]...[/row] → <div class="row ...">...</div>
+  result = result.replace(
+    /\[row([^\]]*)\]([\s\S]*?)\[\/row\]/gi,
+    (_, attrStr, inner) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const classes = ['row'];
+      if (attrs.gap) classes.push(`gap-${attrs.gap}`);
+      if (attrs.class) classes.push(attrs.class);
+      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+      return `<div class="${classes.join(' ')}"${id}>${inner}</div>\n`;
+    }
+  );
+
+  // Pass 3: [grid cols="N" gap="N"]...[/grid] → <div class="grid grid-cols-N ...">...</div>
+  result = result.replace(
+    /\[grid([^\]]*)\]([\s\S]*?)\[\/grid\]/gi,
+    (_, attrStr, inner) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const classes = ['grid'];
+      if (attrs.cols) classes.push(`grid-cols-${attrs.cols}`);
+      if (attrs.gap) classes.push(`gap-${attrs.gap}`);
+      if (attrs.class) classes.push(attrs.class);
+      if (attrs.fullwidth === 'true') classes.push('grid-breakout');
+      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+      return `<div class="${classes.join(' ')}"${id}>${inner}</div>\n`;
+    }
+  );
+
+  return restore(result);
+}
+
+/**
+ * Escape a string for safe use inside an HTML double-quoted attribute value.
+ * Prevents attribute-injection from shortcode attribute values.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeAttr(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Pre-process [card] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [card title="Optional Title" collapsible="true"]
+ *   Body content (supports Markdown).
+ *   [/card]
+ *
+ * Supported attributes:
+ *   title        - Card header title (omit for no header)
+ *   collapsible  - "true" to make the card body toggle on header click
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processCardBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  return restore(scrubbed.replace(
+    /\[card([^\]]*)\]([\s\S]*?)\[\/card\]/gi,
+    (_, attrStr, body) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+        const strAttr = (key) => typeof attrs[key] === 'string' ? attrs[key].trim() : '';
+        const title = strAttr('title');
+        const subtitle = strAttr('subtitle');
+        const icon = strAttr('icon');
+        const footer = strAttr('footer');
+      const collapsible = attrs.collapsible === 'true';
+      const hover = 'hover' in attrs;
+        const variant = strAttr('variant');
+        const extraClass = strAttr('class');
+
+      // Root class list
+      const classes = ['card', 'mb-4'];
+      if (variant === 'primary') classes.push('card-primary');
+      if (hover) classes.push('card-hover');
+      if (collapsible) classes.push('card-collapsible');
+      if (extraClass) classes.push(extraClass);
+
+      const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+      const coll = collapsible ? ' data-collapsible="true"' : '';
+
+      const iconLayout = (attrs['icon-layout'] || 'inline').trim(); // 'inline' | 'stacked'
+
+      // Header — only rendered when at least title or icon is set
+      let headerHtml = '';
+      if (title || icon) {
+        let inner = '';
+        if (icon && iconLayout === 'stacked') {
+          // Stacked: icon centred above title, all centred
+          const subtitleHtml = subtitle ? `<div class="card-subtitle">${subtitle}</div>` : '';
+          inner = `<span data-icon="${escapeAttr(icon)}"></span>` +
+            `<div class="card-title">${title}</div>${subtitleHtml}`;
+          headerHtml = `<div class="card-header card-header-icon-stacked">${inner}</div>`;
+        } else if (icon && title) {
+          // Inline: icon left, title to its right in a flex row
+          const subtitleHtml = subtitle ? `<div class="card-subtitle">${subtitle}</div>` : '';
+          inner = `<span data-icon="${escapeAttr(icon)}"></span>` +
+            `<div class="card-header-content"><div class="card-title">${title}</div>${subtitleHtml}</div>`;
+          headerHtml = `<div class="card-header card-header-icon-inline">${inner}</div>`;
+        } else {
+          // Title only (no icon)
+          inner = `<div class="card-title">${title}</div>`;
+          if (subtitle) inner += `<div class="card-subtitle">${subtitle}</div>`;
+          headerHtml = `<div class="card-header">${inner}</div>`;
+        }
+      }
+
+      const bodyHtml = `<div class="card-body">${marked.parse(body.trim())}</div>`;
+      const footerHtml = footer ? `<div class="card-footer">${footer}</div>` : '';
+
+      return `<div class="${classes.join(' ')}"${coll}${id}>${headerHtml}${bodyHtml}${footerHtml}</div>\n`;
+    }
+  ));
+}
+
+/**
+ * Pre-process [tabs] / [tab] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [tabs id="optional" style="pills"]
+ *   [tab title="First"]Content[/tab]
+ *   [tab title="Second"]Content[/tab]
+ *   [/tabs]
+ *
+ * Supported attributes on [tabs]:
+ *   style  - "pills" for pill-style nav (default: standard underline)
+ *   id     - optional id on the wrapper
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processTabsBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  let counter = 0;
+  const processed = scrubbed.replace(
+    /\[tabs([^\]]*)\]([\s\S]*?)\[\/tabs\]/gi,
+    (_, attrStr, body) => {
+      counter++;
+      const prefix = `dm-tab-${counter}`;
+      const attrs = parseShortcodeAttrs(attrStr);
+      const pillsClass = attrs.style === 'pills' ? ' tabs-pills' : '';
+      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+
+      // Parse inner [tab title="..."] items
+      let tabIdx = 0;
+      const items = [];
+      body.replace(/\[tab([^\]]*)\]([\s\S]*?)\[\/tab\]/gi, (__, tabAttr, tabBody) => {
+        tabIdx++;
+        const tabAttrs = parseShortcodeAttrs(tabAttr);
+        const title = tabAttrs.title || `Tab ${tabIdx}`;
+        const paneId = `${prefix}-${tabIdx}`;
+        // Restore code-block placeholders within this tab body before calling marked,
+        // so fenced code blocks render as <pre><code> rather than surviving as raw text
+        // that would confuse subsequent scrubCodeRegions calls.
+        const restoredBody = restore(tabBody.trim());
+        const bodyHtml = marked.parse(processCardBlocks(processGridBlocks(restoredBody)));
+        items.push({title, paneId, bodyHtml, first: tabIdx === 1});
+      });
+
+      if (!items.length) return '';
+
+      const navItems = items.map(t =>
+        `<button class="tab-item${t.first ? ' active' : ''}">${escapeAttr(t.title)}</button>`
+      ).join('\n    ');
+      const panes = items.map(t =>
+        `<div class="tab-panel${t.first ? ' active' : ''}">${t.bodyHtml}</div>`
+      ).join('\n    ');
+
+      return (
+        `<div class="tabs${pillsClass}"${idAttr}>\n` +
+        `  <div class="tab-list">\n    ${navItems}\n  </div>\n` +
+        `  <div class="tab-content">\n    ${panes}\n  </div>\n` +
+        `</div>\n`
+      );
+    }
+  );
+  return restore(processed);
+}
+
+/**
+ * Pre-process [accordion] / [item] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [accordion multiple="true" id="optional"]
+ *   [item title="Section 1"]Content[/item]
+ *   [item title="Section 2"]Content[/item]
+ *   [/accordion]
+ *
+ * Supported attributes on [accordion]:
+ *   multiple - "true" to allow multiple panels open simultaneously
+ *   id       - optional id on the wrapper
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processAccordionBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  const processed = scrubbed.replace(
+    /\[accordion([^\]]*)\]([\s\S]*?)\[\/accordion\]/gi,
+    (_, attrStr, body) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const multiAttr = attrs.multiple === 'true' ? ' data-multi="true"' : '';
+      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+
+      let items = '';
+      body.replace(/\[item([^\]]*)\]([\s\S]*?)\[\/item\]/gi, (__, itemAttr, itemBody) => {
+        const itemAttrs = parseShortcodeAttrs(itemAttr);
+        const title = itemAttrs.title || 'Item';
+        const bodyHtml = marked.parse(processCardBlocks(processGridBlocks(restore(itemBody.trim()))));
+        items += (
+          `<div class="accordion-item">\n` +
+          `  <h3 class="accordion-header"><button class="accordion-button" type="button">${escapeAttr(title)}` +
+          `<span class="accordion-icon" data-icon="chevron-down"></span></button></h3>\n` +
+          `  <div class="accordion-body"><div class="accordion-content">${bodyHtml}</div></div>\n` +
+          `</div>\n`
+        );
+      });
+
+      return `<div class="accordion"${idAttr}${multiAttr}>\n${items}</div>\n`;
+    }
+  );
+  return restore(processed);
+}
+
+/**
+ * Pre-process [carousel] / [slide] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [carousel autoplay="true" interval="5000" loop="true" animation="slide" id="optional"]
+ *   [slide title="Optional" image="/media/photo.jpg"]Body content[/slide]
+ *   [slide]Text-only slide content[/slide]
+ *   [/carousel]
+ *
+ * Supported attributes on [carousel]:
+ *   autoplay  - "true" to auto-advance slides
+ *   interval  - milliseconds between slides (default 5000)
+ *   loop      - "false" to disable loop (default true)
+ *   animation - "fade" or "slide" (default slide)
+ *   id        - optional id on the wrapper
+ *
+ * Supported attributes on [slide]:
+ *   image - URL of a background/header image
+ *   title - slide heading text
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processCarouselBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  const processed = scrubbed.replace(
+    /\[carousel([^\]]*)\]([\s\S]*?)\[\/carousel\]/gi,
+    (_, attrStr, body) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const dataAttrs = [
+        attrs.autoplay ? ` data-autoplay="${escapeAttr(attrs.autoplay)}"` : '',
+        attrs.interval ? ` data-interval="${escapeAttr(attrs.interval)}"` : '',
+        attrs.loop ? ` data-loop="${escapeAttr(attrs.loop)}"` : '',
+        attrs.animation ? ` data-animation="${escapeAttr(attrs.animation)}"` : ''
+      ].join('');
+      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+
+      let slides = '';
+      body.replace(/\[slide([^\]]*)\]([\s\S]*?)\[\/slide\]/gi, (__, slideAttr, slideBody) => {
+        const slideAttrs = parseShortcodeAttrs(slideAttr);
+        let inner = '';
+        if (slideAttrs.image) {
+          inner += `<img src="${escapeAttr(slideAttrs.image)}" alt="${escapeAttr(slideAttrs.title || '')}">\n`;
+        }
+        const contentHtml = marked.parse(processCardBlocks(processGridBlocks(restore(slideBody.trim()))));
+        if (slideAttrs.title || slideBody.trim()) {
+          inner += `<div class="carousel-slide-content">`;
+          if (slideAttrs.title) inner += `<h2 class="carousel-slide-title">${escapeAttr(slideAttrs.title)}</h2>`;
+          if (slideBody.trim()) inner += `<div class="carousel-slide-description">${contentHtml}</div>`;
+          inner += `</div>`;
+        }
+        slides += `<div class="carousel-slide">${inner}</div>\n`;
+      });
+
+      return `<div class="carousel"${idAttr}${dataAttrs}><div class="carousel-track">${slides}</div></div>\n`;
+    }
+  );
+  return restore(processed);
+}
+
+/**
+ * Pre-process [countdown] self-closing shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [countdown to="2026-12-31" format="DD:HH:mm:ss" /]
+ *   [countdown duration="300" format="mm:ss" /]
+ *
+ * Supported attributes:
+ *   to       - ISO date string for a fixed target date
+ *   duration - seconds to count down from (used if to is absent)
+ *   format   - display format: "mm:ss", "HH:mm:ss", "DD:HH:mm:ss" (default mm:ss)
+ *   id       - optional id on the element
+ *
+ * Client-side site.js initialises .dm-countdown elements via E.timer().
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processCountdownBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  return restore(scrubbed.replace(
+    /\[countdown([^\]]*?)\/\]/gi,
+    (_, attrStr) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const dataAttrs = [
+        attrs.to ? ` data-to="${escapeAttr(attrs.to)}"` : '',
+        attrs.duration ? ` data-duration="${escapeAttr(attrs.duration)}"` : '',
+        attrs.format ? ` data-format="${escapeAttr(attrs.format)}"` : ''
+      ].join('');
+      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+      return `<div class="dm-countdown"${idAttr}${dataAttrs}></div>`;
+    }
+  ));
+}
+
+/**
+ * Pre-process [timeline] / [event] shortcodes before running through marked.
+ *
+ * Renders a Domma Progression (dm-progression) component with event items.
+ *
+ * Syntax:
+ *   [timeline layout="vertical" theme="modern" mode="timeline"]
+ *   [event title="Launch" date="2025-01-15" status="completed" icon="rocket"]
+ *   Description with **Markdown**.
+ *   [/event]
+ *   [/timeline]
+ *
+ * Supported [timeline] attributes:
+ *   layout  - "vertical" (default), "centred", "horizontal"
+ *   theme   - "minimal" (default), "corporate", "modern"
+ *   mode    - "timeline" (default), "roadmap"
+ *   class   - extra CSS classes
+ *   id      - element id
+ *
+ * Supported [event] attributes:
+ *   title   - Event heading (required)
+ *   date    - Display date string
+ *   status  - "planned", "in-progress", "completed", "blocked"
+ *   icon    - Domma icon name
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processTimelineBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  const result = scrubbed.replace(
+    /\[timeline([^\]]*)\]([\s\S]*?)\[\/timeline\]/gi,
+    (_, attrStr, body) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const layout = ['vertical', 'centred', 'horizontal'].includes(attrs.layout) ? attrs.layout : 'vertical';
+      const theme = ['minimal', 'corporate', 'modern'].includes(attrs.theme) ? attrs.theme : 'minimal';
+      const mode = ['timeline', 'roadmap'].includes(attrs.mode) ? attrs.mode : 'timeline';
+
+      const classes = ['dm-progression'];
+      if (attrs.class) classes.push(attrs.class);
+      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+
+      // Parse [event]...[/event] items from body
+      const itemsHtml = body.replace(
+        /\[event([^\]]*)\]([\s\S]*?)\[\/event\]/gi,
+        (__, itemAttrStr, itemBody) => {
+          const ia = parseShortcodeAttrs(itemAttrStr);
+          const title = escapeAttr(ia.title || '');
+          const date = ia.date ? ` data-date="${escapeAttr(ia.date)}"` : '';
+          const status = ia.status ? ` data-status="${escapeAttr(ia.status)}"` : '';
+          const icon = ia.icon ? ` data-icon="${escapeAttr(ia.icon)}"` : '';
+          const descHtml = marked.parse(processCardBlocks(processGridBlocks(restore(itemBody.trim()))));
+          return `<div class="dm-progression-item"${date}${status}${icon}><div class="dm-progression-item-title">${title}</div><div class="dm-progression-item-body">${descHtml}</div></div>`;
+        }
+      );
+
+      return `<div class="${classes.join(' ')}"${idAttr} data-layout="${layout}" data-theme="${theme}" data-mode="${mode}">\n${itemsHtml}</div>\n`;
+    }
+  );
+  return restore(result);
+}
+
+/**
+ * Pre-process [table] shortcodes before running through marked.
+ *
+ * Wraps a GFM Markdown table with Domma CSS classes and a responsive container.
+ *
+ * Syntax:
+ *   [table striped="true" bordered="true" compact="true" caption="Sales Data"]
+ *   | Product | Price |
+ *   | ------- | ----: |
+ *   | Widget  | $9.99 |
+ *   [/table]
+ *
+ * Supported attributes:
+ *   striped  - "true" → .table-striped
+ *   bordered - "true" → .table-bordered
+ *   compact  - "true" → .table-compact
+ *   caption  - text inserted as <caption>
+ *   class    - extra classes appended to .table
+ *   id       - id attribute on the <table>
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+/**
+ * Pre-process [badge] inline shortcodes before running through marked.
+ *
+ * Syntax (paired):
+ *   [badge variant="success"]New[/badge]
+ *   [badge variant="danger" outline pill]Deprecated[/badge]
+ *   [badge variant="warning" size="small"]Beta[/badge]
+ *
+ * Syntax (self-closing, renders empty badge — useful for coloured dots):
+ *   [badge variant="primary" pill /]
+ *
+ * Supported attributes:
+ *   variant - primary (default), secondary, success, danger, warning, info, light, dark
+ *   pill    - flag: add .badge-pill (rounded)
+ *   outline - flag: add .badge-outline
+ *   size    - "small" → .badge-sm | "large" → .badge-lg
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processBadgeBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+
+  const VALID_VARIANTS = new Set([
+    'primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark'
+  ]);
+
+  function buildBadge(attrStr, inner) {
+    const attrs = parseShortcodeAttrs(attrStr || '');
+    const variant = VALID_VARIANTS.has(attrs.variant) ? attrs.variant : 'primary';
+    const classes = ['badge', `badge-${variant}`];
+
+    // Flag attributes (presence in the raw string, not key=value)
+    if (/\bpill\b/i.test(attrStr)) classes.push('badge-pill');
+    if (/\boutline\b/i.test(attrStr)) classes.push('badge-outline');
+    if (attrs.size === 'small') classes.push('badge-sm');
+    if (attrs.size === 'large') classes.push('badge-lg');
+
+    return `<span class="${classes.join(' ')}">${inner}</span>`;
+  }
+
+  // Self-closing: [badge ... /]
+  let result = scrubbed.replace(/\[badge([^\]]*?)\/\]/gi, (_, attrStr) => buildBadge(attrStr, ''));
+
+  // Paired: [badge ...]...[/badge]  (inline only — no newlines inside)
+  result = result.replace(/\[badge([^\]]*)\]([^\n]*?)\[\/badge\]/gi, (_, attrStr, inner) => {
+    return buildBadge(attrStr, inner.trim());
+  });
+
+  return restore(result);
+}
+
+function processTableBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  return restore(scrubbed.replace(
+    /\[table([^\]]*)\]([\s\S]*?)\[\/table\]/gi,
+    (_, attrStr, body) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const classes = ['table'];
+      if (attrs.striped === 'true') classes.push('table-striped');
+      if (attrs.bordered === 'true') classes.push('table-bordered');
+      if (attrs.compact === 'true') classes.push('table-compact');
+      if (attrs.class) classes.push(attrs.class);
+
+      const caption = attrs.caption
+        ? `<caption>${escapeAttr(attrs.caption)}</caption>`
+        : '';
+      const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+
+      let tableHtml = marked.parse(restore(body.trim()));
+
+      tableHtml = tableHtml.replace(
+        '<table>',
+        `<table class="${classes.join(' ')}"${idAttr}>${caption}`
+      );
+
+      return `<div class="table-responsive">${tableHtml}</div>\n`;
+    }
+  ));
+}
+
+/**
+ * Pre-process [hero] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [hero title="Welcome" tagline="Build something great" size="lg" variant="gradient-blue"]
+ *   Optional body content with **Markdown** support.
+ *   [/hero]
+ *
+ * Supported attributes:
+ *   title   - Hero heading (.hero-title)
+ *   tagline - Subtitle text (.hero-subtitle)
+ *   size    - "sm", "lg", "full" → .hero-sm / .hero-lg / .hero-full
+ *   variant - "dark", "primary", "gradient-blue", "gradient-purple",
+ *             "gradient-sunset", "gradient-ocean" → .hero-{variant}
+ *   image   - URL for background-image + adds .hero-cover
+ *   overlay - "light", "dark", "darker", "gradient", "gradient-reverse" → .hero-overlay-{overlay}
+ *   align   - "center" (default) or "left" → .hero-center / .hero-left
+ *   class   - Extra classes appended to .hero
+ *   id      - Element id attribute
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+/**
+ * Pre-process [spacer] self-closing shortcode.
+ *
+ * Syntax:
+ *   [spacer /]                         - uses defaults from layoutOptions config
+ *   [spacer size="24" /]               - explicit pixel height
+ *   [spacer class="my-gap" /]          - extra CSS class
+ *   [spacer size="16" class="mt-4" /]  - both
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processSpacerBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  const opts = getConfig('site')?.layoutOptions ?? {};
+  const defaultSize = opts.spacerSize ?? 8;
+  const defaultClass = opts.spacerClass ?? '';
+  return restore(scrubbed.replace(
+    /\[spacer([^\]]*?)\/?\]/gi,
+    (_, attrStr) => {
+      const attrs = parseShortcodeAttrs(attrStr || '');
+      const size = parseInt(attrs.size, 10) || defaultSize;
+      const extra = attrs.class || defaultClass;
+      const classes = ['dm-spacer', extra].filter(Boolean).join(' ');
+      return `<div class="${classes}" style="height:${size}px" aria-hidden="true"></div>\n`;
+    }
+  ));
+}
+
+/**
+ * Pre-process [center]...[/center] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [center]Centred content here[/center]
+ *   [center class="my-class"]Content[/center]
+ *
+ * Supported attributes:
+ *   class - Extra CSS classes on the wrapper div
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processCenterBlocks(markdown) {
+    const {scrubbed, restore} = scrubCodeRegions(markdown);
+    return restore(scrubbed.replace(
+        /\[center([^\]]*)\]([\s\S]*?)\[\/center\]/gi,
+        (_, attrStr, body) => {
+            const attrs = parseShortcodeAttrs(attrStr);
+            const classAttr = attrs.class ? ` class="${escapeAttr(attrs.class)}"` : '';
+            const bodyHtml = marked.parse(processCardBlocks(processGridBlocks(restore(body.trim()))));
+            return `<div style="text-align:center;"${classAttr}>${bodyHtml}</div>\n`;
+        }
+    ));
+}
+
+/**
+ * Pre-process [icon] self-closing shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [icon name="arrow-right" /]
+ *   [icon name="star" size="24" color="#f59e0b" class="my-icon" /]
+ *
+ * Supported attributes:
+ *   name  - Domma icon name (required). Also accepted as src= for convenience.
+ *   size  - Width and height in px (default: 1em via CSS)
+ *   color - CSS colour applied via style
+ *   class - Extra CSS classes
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processIconBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  return restore(scrubbed.replace(
+    /\[icon([^\]]*?)\/\]/gi,
+    (_, attrStr) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const name = attrs.name || attrs.src || '';
+      if (!name) return '';
+      const classes = ['dm-icon', attrs.class].filter(Boolean).join(' ');
+      const sizeAttr = attrs.size ? ` data-icon-size="${parseInt(attrs.size, 10)}"` : '';
+      const colorAttr = attrs.color ? ` data-icon-colour="${escapeAttr(attrs.color)}"` : '';
+      return `<span data-icon="${escapeAttr(name)}" class="${escapeAttr(classes)}"${sizeAttr}${colorAttr}></span>`;
+    }
+  ));
+}
+
+/**
+ * Pre-process [form] self-closing shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [form name="contact" /]
+ *   [form name="newsletter" class="my-form" /]
+ *
+ * Supported attributes:
+ *   name  - Form slug as configured in the form-builder (required). Also accepted as slug=.
+ *   class - Extra CSS classes on the wrapper div
+ *   id    - Element id attribute
+ *
+ * The form-builder's injected client script scans for [data-form] and renders the form.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+const FORMS_DIR = path.resolve(__dirname_md, '../../content/forms');
+
+async function processFormBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  const regex = /\[form([^\]]*?)\/\]/gi;
+  let result = scrubbed;
+  const matches = [];
+  let m;
+  while ((m = regex.exec(scrubbed)) !== null) {
+    matches.push({full: m[0], attrStr: m[1], index: m.index});
+  }
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const {full, attrStr, index} = matches[i];
+    const attrs = parseShortcodeAttrs(attrStr);
+    const slug = attrs.name || attrs.slug || '';
+    if (!slug) {
+      result = result.slice(0, index) + '' + result.slice(index + full.length);
+      continue;
+    }
+      if (!/^[a-z0-9][a-z0-9_-]*$/i.test(slug)) {
+          result = result.slice(0, index) + `<div class="cms-form-error">Invalid form slug: ${escapeAttr(slug)}</div>` + result.slice(index + full.length);
+          continue;
+      }
+    let replacement;
+    try {
+      const filePath = path.resolve(FORMS_DIR, `${slug}.json`);
+      if (!filePath.startsWith(FORMS_DIR + path.sep)) throw new Error('Invalid slug');
+      const raw = await readFile(filePath, 'utf8');
+      const form = JSON.parse(raw);
+      const encoded = Buffer.from(JSON.stringify(form)).toString('base64');
+        const extraClass = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
+        const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+        replacement = `<div class="cms-form-embed${extraClass}" data-form-inline="${escapeAttr(encoded)}"${idAttr}></div>`;
+    } catch {
+        const extraClass = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
+        const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+        replacement = `<div class="cms-form-embed cms-form-embed--error${extraClass}" data-form-slug="${escapeAttr(slug)}"${idAttr}><p><em>Form not found: ${escapeHtmlText(slug)}</em></p></div>`;
+    }
+    result = result.slice(0, index) + replacement + result.slice(index + full.length);
+  }
+  return restore(result);
+}
+
+function processHeroBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  const result = scrubbed.replace(
+    /\[hero([^\]]*)\]([\s\S]*?)\[\/hero\]/gi,
+    (_, attrStr, body) => {
+      const attrs = parseShortcodeAttrs(attrStr);
+      const title = attrs.title || '';
+      const tagline = attrs.tagline || '';
+      const size = attrs.size || '';
+      const variant = attrs.variant || '';
+      const image = attrs.image || '';
+      const overlay = attrs.overlay || '';
+      const align = attrs.align || 'center';
+      const fullwidth = attrs.fullwidth === 'true';
+      const cls = attrs.class || '';
+      const id = attrs.id || '';
+      const bg = attrs.bg || '';
+
+      const twinkle = 'twinkle' in attrs;
+      const twinkleCount = attrs['twinkle-count'] || '';
+      const twinkleColour = attrs['twinkle-colour'] || '';
+      const blobs = 'blobs' in attrs;
+      const blobsType = attrs['blobs-type'] || 'float-blobs';
+
+      const classes = ['hero'];
+      if (size) classes.push(`hero-${size}`);
+      if (variant) classes.push(`hero-${variant}`);
+      if (align) classes.push(`hero-${align}`);
+      if (image) classes.push('hero-cover');
+      if (overlay) classes.push(`hero-overlay-${overlay}`);
+      if (fullwidth) classes.push('hero-breakout');
+      if (cls) classes.push(cls);
+      if (twinkle) classes.push('dm-fx-twinkle');
+      if (blobs) classes.push(`bg-ambient-${blobsType}`);
+
+      const styleParts = [];
+      if (image) styleParts.push(`background-image:url('${escapeAttr(image)}')`);
+      if (bg) styleParts.push(`background-color:${escapeAttr(bg)}`);
+      const style = styleParts.length ? ` style="${styleParts.join(';')}"` : '';
+      const idAttr = id ? ` id="${escapeAttr(id)}"` : '';
+
+      const twinkleAttrs = twinkle
+        ? (twinkleCount ? ` data-fx-count="${escapeAttr(twinkleCount)}"` : '') +
+        (twinkleColour ? ` data-fx-colour="${escapeAttr(twinkleColour)}"` : '')
+        : '';
+
+      const processedBody = processBadgeBlocks(processCardBlocks(processGridBlocks(restore(body.trim()))));
+
+      let inner = '<div class="hero-content">';
+      if (title) inner += `<h1 class="hero-title hero-title-responsive">${escapeAttr(title)}</h1>`;
+      if (tagline) inner += `<p class="hero-subtitle hero-subtitle-responsive">${escapeAttr(tagline)}</p>`;
+      if (processedBody) inner += `<div class="hero-body">${marked.parse(processedBody)}</div>`;
+      inner += '</div>';
+
+      return `<div class="${classes.join(' ')}"${idAttr}${style}${twinkleAttrs}>${inner}</div>\n`;
+    }
+  );
+  return restore(result);
+}
+
+/**
+ * Pre-process [slideover] shortcodes before running through marked.
+ *
+ * Syntax:
+ *   [slideover title="More Info" trigger="Read more" size="md" position="right"]
+ *   Markdown body here.
+ *   [/slideover]
+ *
+ * Outputs a trigger button and a hidden content div with data attributes.
+ * Client-side site.js wires up the click handler to open a Domma slideover.
+ * Attribute values are HTML-escaped to prevent injection.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processSlideoverBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  let counter = 0;
+  const processed = scrubbed.replace(
+    /\[slideover([^\]]*)\]([\s\S]*?)\[\/slideover\]/gi,
+    (_, attrStr, body) => {
+      counter++;
+      const id = `dm-so-${counter}`;
+      const attrs = parseShortcodeAttrs(attrStr);
+      const title = escapeAttr(attrs.title || '');
+      const trigger = escapeAttr(attrs.trigger || 'Open');
+      const size = escapeAttr(attrs.size || 'md');
+      const position = escapeAttr(attrs.position || 'right');
+      const bodyHtml = marked.parse(processCardBlocks(processGridBlocks(restore(body.trim()))));
+      return (
+        `<button class="btn btn-link dm-so-trigger" data-so-target="${id}">${trigger}</button>\n` +
+        `<div class="dm-so-content" id="${id}" style="display:none" ` +
+        `data-so-title="${title}" data-so-size="${size}" data-so-position="${position}">${bodyHtml}</div>\n`
+      );
+    }
+  );
+  return restore(processed);
+}
+
+/**
+ * Pre-process [dconfig] shortcodes before running through marked.
+ *
+ * Extracts JSON config blocks and base64-encodes them into hidden divs.
+ * Multiple blocks on one page are supported and merged client-side.
+ * Invalid JSON blocks are silently dropped (no render output).
+ *
+ * Syntax:
+ *   [dconfig]
+ *   { "#btn": { "events": { "click": { "target": "#panel", "toggleClass": "hidden" } } } }
+ *   [/dconfig]
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processDConfigBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+  const processed = scrubbed.replace(
+    /\[dconfig\]([\s\S]*?)\[\/dconfig\]/gi,
+    (_, jsonStr) => {
+      try {
+        JSON.parse(jsonStr.trim()); // validate before encoding
+        const encoded = Buffer.from(jsonStr.trim(), 'utf8').toString('base64');
+        return `<div class="dm-page-config" style="display:none" data-config="${encoded}"></div>\n`;
+      } catch {
+        return ''; // invalid JSON — drop silently
+      }
+    }
+  );
+  return restore(processed);
+}
+
+/**
+ * Pre-process [cta] shortcodes into button elements that trigger Actions.
+ *
+ * Wrapping form:   [cta action="slug" entry="id" style="primary" icon="check" confirm="Sure?"]Label[/cta]
+ * Self-closing:    [cta action="slug" entry="id" label="Run" /]
+ *
+ * Outputs a <button class="btn btn-{style} dm-cta-trigger"> with data-action and data-entry
+ * attributes. Client-side wiring in site.js handles click → POST /api/actions/:slug/public.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function processCtaBlocks(markdown) {
+  const {scrubbed, restore} = scrubCodeRegions(markdown);
+
+  function buildButton(attrStr, body) {
+    const attrs = parseShortcodeAttrs(attrStr);
+    const action = attrs.action || '';
+    if (!action) return '';
+    const entry  = attrs.entry  || '';
+
+    const style   = attrs.style   || 'primary';
+    const icon    = attrs.icon    || '';
+    const size    = attrs.size    || '';
+    const confirm = attrs.confirm || '';
+    const label   = body ? body.trim() : (attrs.label || 'Run');
+
+    let cls = `btn btn-${escapeAttr(style)} dm-cta-trigger`;
+    if (size) cls += ` btn-${escapeAttr(size)}`;
+
+    let dataAttrs = `data-action="${escapeAttr(action)}" data-entry="${escapeAttr(entry)}"`;
+    if (confirm) dataAttrs += ` data-confirm="${escapeAttr(confirm)}"`;
+
+    const iconHtml = icon ? `<span data-icon="${escapeAttr(icon)}"></span> ` : '';
+    return `<button class="${cls}" ${dataAttrs}>${iconHtml}${escapeHtmlText(label)}</button>`;
+  }
+
+  // Self-closing: [cta attrs /]
+  let processed = scrubbed.replace(/\[cta([^\]]*?)\/\]/gi, (_, attrStr) => buildButton(attrStr, null));
+  // Wrapping: [cta attrs]body[/cta]
+  processed = processed.replace(/\[cta([^\]]*?)\]([\s\S]*?)\[\/cta\]/gi, (_, attrStr, body) => buildButton(attrStr, body));
+
+  return restore(processed);
+}
+
+/**
+ * Parse a Markdown file string into frontmatter data and rendered HTML.
+ *
+ * @param {string} raw - Raw file content (frontmatter + Markdown body)
+ * @returns {{ data: object, content: string, html: string }}
+ */
+export async function parseMarkdown(raw) {
+  const {data, content} = matter(raw);
+  const extensions = getSanitizeExtensions();
+
+  // Pipeline:
+  // beforeParse → collection → view → dconfig → plugin shortcodes → tabs → accordion → carousel
+    //   → countdown → timeline → spacer → center → icon → form → hero → table → badge → cta → grid → card
+  //   → slideover → marked → sanitize → afterParse
+  const preprocessed = applyTransforms('markdown:beforeParse', content);
+  const withCollection = await processCollectionBlocks(preprocessed);
+  const withView = await processViewBlocks(withCollection);
+  const withDconfig = processDConfigBlocks(withView);
+  const withPluginShortcodes = processPluginShortcodes(withDconfig);
+  const withTabs = processTabsBlocks(withPluginShortcodes);
+  const withAccordion = processAccordionBlocks(withTabs);
+  const withCarousel = processCarouselBlocks(withAccordion);
+  const withCountdown = processCountdownBlocks(withCarousel);
+  const withTimeline = processTimelineBlocks(withCountdown);
+  const withSpacer = processSpacerBlocks(withTimeline);
+    const withCenter = processCenterBlocks(withSpacer);
+    const withIcon = processIconBlocks(withCenter);
+  const withForm = await processFormBlocks(withIcon);
+  const withHero = processHeroBlocks(withForm);
+  const withTable = processTableBlocks(withHero);
+  const withBadge = processBadgeBlocks(withTable);
+  const withCta = processCtaBlocks(withBadge);
+  const withGrid = processGridBlocks(withCta);
+  const withCard = processCardBlocks(withGrid);
+  const withSlideover = processSlideoverBlocks(withCard);
+  const rendered = marked.parse(withSlideover);
+
+  const sanitized = sanitizeHtml(rendered, {
+    allowedTags: sanitizeHtml.defaults.allowedTags.concat([
+      'img', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+      'form', 'input', 'textarea', 'select', 'option', 'optgroup',
+      'button', 'label', 'fieldset', 'legend',
+      ...extensions.tags
+    ]),
+    allowedAttributes: {
+      ...sanitizeHtml.defaults.allowedAttributes,
+      '*': ['class', 'id', 'style', 'data-*'],
+      img: ['src', 'alt', 'title', 'width', 'height', 'loading'],
+      form: ['action', 'method'],
+      input: ['type', 'name', 'placeholder', 'value', 'required', 'disabled',
+        'readonly', 'min', 'max', 'step', 'pattern', 'maxlength',
+        'minlength', 'checked', 'autocomplete'],
+      textarea: ['name', 'placeholder', 'rows', 'cols', 'required',
+        'disabled', 'readonly', 'maxlength'],
+      select: ['name', 'required', 'disabled', 'multiple'],
+      option: ['value', 'selected', 'disabled'],
+      optgroup: ['label', 'disabled'],
+      button: ['type', 'disabled', 'data-action', 'data-entry', 'data-confirm'],
+      label: ['for'],
+      fieldset: ['disabled'],
+      ...extensions.attributes
+    }
+  });
+
+  const html = applyTransforms('markdown:afterParse', sanitized);
+  return {data, content, html};
+}
+
+/**
+ * Serialise a page object back to a Markdown file string.
+ *
+ * @param {object} frontmatter - Page metadata fields
+ * @param {string} body - Markdown body
+ * @returns {string}
+ */
+export function serialiseMarkdown(frontmatter, body) {
+    return matter.stringify(body || '', frontmatter);
+}