create-portfoliable 1.2.14 → 1.2.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-portfoliable",
-  "version": "1.2.14",
+  "version": "1.2.16",
   "description": "Unified Portfoliable package with initializer and runtime CLI",
   "private": false,
   "type": "module",

package/scripts/release-orchestrator.mjs

@@ -12,6 +12,7 @@ import { pathToFileURL } from "node:url";
 const REPO_URL = "https://github.com/portfoliablejs/portfoliable";
 // Enables dry-run behavior when --dry-run is provided on process args.
 const isDryRun = process.argv.includes("--dry-run");
+const isPreparePr = process.argv.includes("--prepare-pr");
 // Enables signing release commit and tag objects when RELEASE_SIGN=true.
 const shouldSign = process.env.RELEASE_SIGN === "true";
 
@@ -410,6 +411,11 @@ function run() {
   }
   git(commitArgs);
 
+  if (isPreparePr) {
+    console.log("Release PR preparation enabled; skipping tag creation until merge.");
+    return;
+  }
+
   // Creates annotated or signed tags for each release if tag is not already present.
   for (const plan of releases) {
     // Checks whether target tag already exists in repository.

package/scripts/scaffold-case.mjs

@@ -10,11 +10,13 @@ import { readLocaleConfigFromI18nConfig, resolveI18nConfigPath } from '../templa
 
 // MARK: DEFAULTS
 // Defines default output path used when no known case root can be resolved.
-const DEFAULT_OUTPUT = 'src/content/cases/my-case/case.md';
+const DEFAULT_OUTPUT = 'src/content/cases/my-case/my-case.md';
 // Defines default case name used when no name is provided.
 const DEFAULT_NAME = 'My Case';
 // Defines candidate case roots in priority order for local repo and consumer apps.
 const DEFAULT_CASES_ROOTS = ['templates/src/content/cases', 'src/content/cases'];
+// Defines order increment applied when choosing the next generated case order value.
+const CASE_ORDER_STEP = 10;
 
 // MARK: DEFAULT CASE TEMPLATE
 // Centralized defaults used when scaffolding new cases.
@@ -178,15 +180,110 @@ function resolveCasesRoots(cwd) {
 }
 
   // Computes default output markdown path from first discovered cases root.
-function resolveDefaultOutFile(cwd, name) {
-  const caseSlug = toSlug(name);
+function resolvePrimaryCasesRoot(cwd) {
   const roots = resolveCasesRoots(cwd);
   if (roots.length > 0) {
-    const target = path.join(roots[0], caseSlug, 'case.md');
-    return path.relative(cwd, target);
+    return roots[0];
   }
 
-  return DEFAULT_OUTPUT;
+  return path.resolve(cwd, DEFAULT_CASES_ROOTS[0]);
+}
+
+function walkMarkdownFiles(rootDir, files = []) {
+  if (!fs.existsSync(rootDir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  entries.forEach((entry) => {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      walkMarkdownFiles(entryPath, files);
+      return;
+    }
+
+    if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+      files.push(entryPath);
+    }
+  });
+
+  return files;
+}
+
+function collectExistingCaseMetadata(caseRoot) {
+  const usedSlugs = new Set();
+  const caseOrders = [];
+  const markdownFiles = walkMarkdownFiles(caseRoot, []);
+
+  markdownFiles.forEach((filePath) => {
+    const relativePath = path.relative(caseRoot, filePath);
+    const pathSegments = relativePath.split(path.sep).filter(Boolean);
+    const folderSlug = pathSegments.length > 1 ? pathSegments[0] : '';
+    if (folderSlug) {
+      usedSlugs.add(toSlug(folderSlug));
+    }
+
+    const fileSlug = toSlug(path.basename(filePath, '.md'));
+    if (fileSlug) {
+      usedSlugs.add(fileSlug);
+    }
+
+    let source = '';
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return;
+    }
+
+    const idMatch = source.match(/"id"\s*:\s*"([^"]+)"/);
+    if (idMatch?.[1]) {
+      usedSlugs.add(toSlug(idMatch[1]));
+    }
+
+    const slugBlockMatch = source.match(/"slugByLocale"\s*:\s*\{([\s\S]*?)\}/);
+    if (slugBlockMatch?.[1]) {
+      const slugValues = slugBlockMatch[1].matchAll(/:\s*"([^"]+)"/g);
+      for (const slugMatch of slugValues) {
+        if (slugMatch?.[1]) {
+          usedSlugs.add(toSlug(slugMatch[1]));
+        }
+      }
+    }
+
+    const orderMatch = source.match(/"caseOrder"\s*:\s*(\d+)/);
+    if (orderMatch?.[1]) {
+      const parsedOrder = Number.parseInt(orderMatch[1], 10);
+      if (Number.isFinite(parsedOrder)) {
+        caseOrders.push(parsedOrder);
+      }
+    }
+  });
+
+  return { usedSlugs, caseOrders };
+}
+
+function resolveUniqueSlug(baseSlug, usedSlugs) {
+  if (!usedSlugs.has(baseSlug)) {
+    return baseSlug;
+  }
+
+  let index = 2;
+  while (usedSlugs.has(`${baseSlug}-${index}`)) {
+    index += 1;
+  }
+
+  return `${baseSlug}-${index}`;
+}
+
+function resolveDefaultScaffoldValues(cwd, name) {
+  const caseRoot = resolvePrimaryCasesRoot(cwd);
+  const { usedSlugs, caseOrders } = collectExistingCaseMetadata(caseRoot);
+  const baseSlug = toSlug(name);
+  const slug = resolveUniqueSlug(baseSlug, usedSlugs);
+  const maxOrder = caseOrders.length > 0 ? Math.max(...caseOrders) : DEFAULT_CASE_TEMPLATE.caseOrder - CASE_ORDER_STEP;
+  const caseOrder = maxOrder + CASE_ORDER_STEP;
+  const outFile = path.relative(cwd, path.join(caseRoot, slug, `${slug}.md`));
+  return { outFile, slug, caseOrder };
 }
 
 // Derives case slug from output path patterns or fallback case name.
@@ -277,7 +374,7 @@ function formatCaseConfigBlock(caseConfig) {
 }
 
 // Build the markdown scaffold body used for new cases.
-function buildTemplate({ name, slug, localeCodes }) {
+function buildTemplate({ name, slug, caseOrder, localeCodes }) {
   // Derives normalized title for localized title fields.
   const title = toTitle(name);
   // Derives normalized slug for id and localized route slug fields.
@@ -292,7 +389,7 @@ function buildTemplate({ name, slug, localeCodes }) {
 
   const caseConfig = {
     id: cleanSlug,
-    caseOrder: DEFAULT_CASE_TEMPLATE.caseOrder,
+    caseOrder,
     slugByLocale: localizedValue({ default: cleanSlug }),
     socialImage: localizedValue({ default: DEFAULT_CASE_TEMPLATE.socialImage }),
     title: {
@@ -421,11 +518,24 @@ function buildTemplate({ name, slug, localeCodes }) {
 export function runCaseScaffold(options = {}) {
   // Resolves working directory used for output file path calculation.
   const cwd = options.cwd || process.cwd();
-  // Resolves output filename using option or context-aware default fallback.
-  const outFile = options.outFile || resolveDefaultOutFile(cwd, options.name || DEFAULT_NAME);
   // Resolves case display name using option or default fallback.
   const name = options.name || DEFAULT_NAME;
-  const caseSlug = resolveCaseSlugFromOutput(outFile, name);
+  const hasExplicitOutFile = typeof options.outFile === 'string' && options.outFile.trim().length > 0;
+
+  const defaultScaffold = hasExplicitOutFile
+    ? null
+    : resolveDefaultScaffoldValues(cwd, name);
+
+  // Resolves output filename using option or context-aware default fallback.
+  const outFile = hasExplicitOutFile
+    ? options.outFile
+    : (defaultScaffold?.outFile || DEFAULT_OUTPUT);
+
+  const caseSlug = hasExplicitOutFile
+    ? resolveCaseSlugFromOutput(outFile, name)
+    : defaultScaffold.slug;
+
+  const caseOrder = defaultScaffold?.caseOrder ?? DEFAULT_CASE_TEMPLATE.caseOrder;
   // Coerces force flag to explicit boolean.
   const force = Boolean(options.force);
   // Resolves absolute output path for scaffold file.
@@ -444,7 +554,7 @@ export function runCaseScaffold(options = {}) {
   }
 
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.writeFileSync(outputPath, buildTemplate({ name, slug: caseSlug, localeCodes }), 'utf8');
+  fs.writeFileSync(outputPath, buildTemplate({ name, slug: caseSlug, caseOrder, localeCodes }), 'utf8');
   console.log(`[scaffold-case] Created starter case file: ${outputPath}`);
   return 0;
 }

package/src/App.js

@@ -4662,7 +4662,7 @@ class AppShell extends HTMLElement {
                 ].join('::');
 
                 if (this._caseViewRenderSignature !== caseRenderSignature) {
-                    caseView.innerHTML = caseMarkup;
+                    caseView.innerHTML = this._normalizeArticleMediaUrls(caseMarkup);
                     this._caseViewRenderSignature = caseRenderSignature;
                 }
 
@@ -5365,7 +5365,9 @@ class AppShell extends HTMLElement {
         const thumbBrand = activeCase.thumbBrand || 'apple';
         const thumbModel = activeCase.thumbModel || 'Apple iPhone 12';
         const thumbColor = activeCase.thumbColor || 'Black';
-        const subtitleSrc = String(this.getLangCurrentLocaleOnly(this._resolveCasePrimaryVttProp(activeCase)) || '').trim();
+        const subtitleSrc = this._resolveRuntimeMediaUrl(
+            this.getLangCurrentLocaleOnly(this._resolveCasePrimaryVttProp(activeCase))
+        );
         const rawSubtitleConfig = this._resolveCasePrimaryVttProp(activeCase);
         const {
             breadcrumbMenuLabels,
@@ -5547,7 +5549,7 @@ class AppShell extends HTMLElement {
         const composedHtml = this.getLang(aboutPayload.bodyHtml) || '';
 
         if (aboutArticle.dataset.aboutHtml !== composedHtml) {
-            aboutArticle.innerHTML = composedHtml;
+            aboutArticle.innerHTML = this._normalizeArticleMediaUrls(composedHtml);
             aboutArticle.dataset.aboutHtml = composedHtml;
         }
 
@@ -5648,6 +5650,34 @@ class AppShell extends HTMLElement {
         });
     }
 
+    _normalizeArticleMediaUrls(html) {
+        if (typeof document === 'undefined') return String(html || '');
+
+        const template = document.createElement('template');
+        template.innerHTML = String(html || '');
+        template.content.querySelectorAll('[src]').forEach((element) => {
+            const source = element.getAttribute('src');
+            if (source) element.setAttribute('src', this._resolveRuntimeMediaUrl(source));
+        });
+        template.content.querySelectorAll('[poster]').forEach((element) => {
+            const poster = element.getAttribute('poster');
+            if (poster) element.setAttribute('poster', this._resolveRuntimeMediaUrl(poster));
+        });
+        template.content.querySelectorAll('[srcset]').forEach((element) => {
+            const srcset = element.getAttribute('srcset');
+            if (!srcset) return;
+            const normalizedSrcset = srcset.split(',').map((candidate) => {
+                const parts = candidate.trim().split(/\s+/);
+                if (!parts[0]) return candidate;
+                parts[0] = this._resolveRuntimeMediaUrl(parts[0]);
+                return parts.join(' ');
+            }).join(', ');
+            element.setAttribute('srcset', normalizedSrcset);
+        });
+
+        return template.innerHTML;
+    }
+
     _resolveLocalizedConfigText(value) {
         if (typeof value === 'string') return value;
         if (!value || typeof value !== 'object') return '';

package/src/parser/markdown-rendering.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { renderLocalizedMarkdownHtml } from './markdown.js';
+
+describe('case markdown rendering', () => {
+  it('preserves authored HTML image sizing attributes', () => {
+    const html = renderLocalizedMarkdownHtml(
+      '<img src="src/content/cases/example/image.avif" alt="Example" width="300">',
+      ['en']
+    ).htmlByLocale.en;
+
+    expect(html).toContain('<img src="src/content/cases/example/image.avif" alt="Example" width="300">');
+  });
+
+  it('renders Mermaid fences as diagram elements', () => {
+    const html = renderLocalizedMarkdownHtml('```mermaid\ngraph TD\n  A --> B\n```', ['en'])
+      .htmlByLocale.en;
+
+    expect(html).toContain('<mermaid-diagram>');
+    expect(html).toContain('graph TD');
+    expect(html).not.toContain('<pre><code>');
+  });
+
+  it('keeps ordinary fenced code blocks as code', () => {
+    const html = renderLocalizedMarkdownHtml('```javascript\nconst answer = 42;\n```', ['en'])
+      .htmlByLocale.en;
+
+    expect(html).toContain('<pre><code>');
+    expect(html).toContain('const answer = 42;');
+  });
+});

package/src/parser/markdown.js

@@ -10,7 +10,7 @@ import markdownItTaskLists from 'markdown-it-task-lists';
 // MARK: MARKDOWN RENDERER
 // Uses markdown-it + plugins to support broad markdown syntax for case content.
 const markdownRenderer = new MarkdownIt({
-  html: false,
+  html: true,
   linkify: true,
   typographer: true,
   breaks: false
@@ -56,6 +56,16 @@ markdownRenderer.renderer.rules.link_open = (tokens, idx, options, env, self) =>
   return self.renderToken(tokens, idx, options);
 };
 
+// Emits Mermaid fences as the Valence custom element instead of a code block.
+markdownRenderer.renderer.rules.fence = (tokens, idx) => {
+  const token = tokens[idx];
+  if (String(token.info || '').trim().split(/\s+/)[0].toLowerCase() !== 'mermaid') {
+    return `<pre><code>${markdownRenderer.utils.escapeHtml(token.content)}</code></pre>\n`;
+  }
+
+  return `<mermaid-diagram>${markdownRenderer.utils.escapeHtml(token.content)}</mermaid-diagram>\n`;
+};
+
 // MARK: VALIDATION CONTRACTS
 // Lists required scalar config fields that every case must define.
 const REQUIRED_SCALAR_FIELDS = ['id', 'thumbCategory', 'thumbBrand', 'thumbModel', 'thumbColor'];

package/templates/scripts/scaffold-case.mjs

@@ -127,10 +127,14 @@ function readSupportedLocales(cwd = process.cwd()) {
 }
 
 // === DEFAULTS ===
-// Defines the default output path used when callers do not provide --out.
-const DEFAULT_OUTPUT = 'src/content/cases/my-case/case.md';
+// Defines the default output path fallback used when no cases root is available.
+const DEFAULT_OUTPUT = 'src/content/cases/my-case/my-case.md';
 // Defines fallback title text used when callers do not provide --name.
 const DEFAULT_NAME = 'My Case';
+// Defines candidate case roots in priority order for local repo and consumer apps.
+const DEFAULT_CASES_ROOTS = ['src/content/cases', 'templates/src/content/cases'];
+// Defines order increment applied when choosing the next generated case order value.
+const CASE_ORDER_STEP = 10;
 
 // === STRING NORMALIZATION HELPERS ===
 // Converts arbitrary text into a markdown-safe slug used for id and localized slug fields.
@@ -165,7 +169,7 @@ function parseArgs(argv) {
   const args = argv.slice(2);
   // Initializes parser output with defaults so missing flags still produce valid output.
   const options = {
-    outFile: DEFAULT_OUTPUT,
+    outFile: '',
     name: DEFAULT_NAME,
     force: false
   };
@@ -194,9 +198,130 @@ function parseArgs(argv) {
   return options;
 }
 
+function resolveCasesRoots(cwd) {
+  return DEFAULT_CASES_ROOTS
+    .map((relativeRoot) => path.resolve(cwd, relativeRoot))
+    .filter((absoluteRoot) => fs.existsSync(absoluteRoot) && fs.statSync(absoluteRoot).isDirectory());
+}
+
+function resolvePrimaryCasesRoot(cwd) {
+  const discoveredRoots = resolveCasesRoots(cwd);
+  if (discoveredRoots.length > 0) {
+    return discoveredRoots[0];
+  }
+
+  return path.resolve(cwd, DEFAULT_CASES_ROOTS[0]);
+}
+
+function walkMarkdownFiles(rootDir, files = []) {
+  if (!fs.existsSync(rootDir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  entries.forEach((entry) => {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      walkMarkdownFiles(entryPath, files);
+      return;
+    }
+
+    if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+      files.push(entryPath);
+    }
+  });
+
+  return files;
+}
+
+function collectExistingCaseMetadata(caseRoot) {
+  const usedSlugs = new Set();
+  const caseOrders = [];
+  const markdownFiles = walkMarkdownFiles(caseRoot, []);
+
+  markdownFiles.forEach((filePath) => {
+    const relativePath = path.relative(caseRoot, filePath);
+    const pathSegments = relativePath.split(path.sep).filter(Boolean);
+    const folderSlug = pathSegments.length > 1 ? pathSegments[0] : '';
+    if (folderSlug) {
+      usedSlugs.add(toSlug(folderSlug));
+    }
+
+    const fileSlug = toSlug(path.basename(filePath, '.md'));
+    if (fileSlug) {
+      usedSlugs.add(fileSlug);
+    }
+
+    let source = '';
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return;
+    }
+
+    const idMatch = source.match(/"id"\s*:\s*"([^"]+)"/);
+    if (idMatch?.[1]) {
+      usedSlugs.add(toSlug(idMatch[1]));
+    }
+
+    const slugBlockMatch = source.match(/"slugByLocale"\s*:\s*\{([\s\S]*?)\}/);
+    if (slugBlockMatch?.[1]) {
+      const slugValues = slugBlockMatch[1].matchAll(/:\s*"([^"]+)"/g);
+      for (const slugMatch of slugValues) {
+        if (slugMatch?.[1]) {
+          usedSlugs.add(toSlug(slugMatch[1]));
+        }
+      }
+    }
+
+    const orderMatch = source.match(/"caseOrder"\s*:\s*(\d+)/);
+    if (orderMatch?.[1]) {
+      const parsedOrder = Number.parseInt(orderMatch[1], 10);
+      if (Number.isFinite(parsedOrder)) {
+        caseOrders.push(parsedOrder);
+      }
+    }
+  });
+
+  return { usedSlugs, caseOrders };
+}
+
+function resolveUniqueSlug(baseSlug, usedSlugs) {
+  if (!usedSlugs.has(baseSlug)) {
+    return baseSlug;
+  }
+
+  let index = 2;
+  while (usedSlugs.has(`${baseSlug}-${index}`)) {
+    index += 1;
+  }
+
+  return `${baseSlug}-${index}`;
+}
+
+function resolveCaseSlugFromOutput(outFile, name) {
+  const basename = path.basename(outFile || '');
+  if (basename.toLowerCase() === 'case.md') {
+    return toSlug(path.basename(path.dirname(outFile || '')) || name);
+  }
+
+  return toSlug(path.basename(outFile || '', '.md') || name);
+}
+
+function resolveDefaultScaffoldValues(cwd, name) {
+  const caseRoot = resolvePrimaryCasesRoot(cwd);
+  const { usedSlugs, caseOrders } = collectExistingCaseMetadata(caseRoot);
+  const baseSlug = toSlug(name);
+  const slug = resolveUniqueSlug(baseSlug, usedSlugs);
+  const maxOrder = caseOrders.length > 0 ? Math.max(...caseOrders) : DEFAULT_CASE_TEMPLATE.caseOrder - CASE_ORDER_STEP;
+  const caseOrder = maxOrder + CASE_ORDER_STEP;
+  const outFile = path.relative(cwd, path.join(caseRoot, slug, `${slug}.md`));
+  return { outFile, slug, caseOrder };
+}
+
 // === TEMPLATE CONSTRUCTION ===
 // Produces localized starter markdown content for a new case study.
-function buildTemplate({ name, slug }) {
+function buildTemplate({ name, slug, caseOrder }) {
   // Derives a normalized visible title from provided input.
   const title = toTitle(name);
   // Derives a safe slug fallback from either explicit slug or case name.
@@ -212,7 +337,7 @@ function buildTemplate({ name, slug }) {
 
   const caseConfig = {
     id: cleanSlug,
-    caseOrder: DEFAULT_CASE_TEMPLATE.caseOrder,
+    caseOrder,
     slugByLocale: localizedValue({ default: cleanSlug }),
     socialImage: localizedValue({ default: DEFAULT_CASE_TEMPLATE.socialImage }),
     title: {
@@ -397,25 +522,29 @@ function formatCaseConfigBlock(caseConfig) {
   return lines.join('\n');
 }
 
-function resolveCaseSlugFromOutput(outFile, name) {
-  const basename = path.basename(outFile || '');
-  if (basename.toLowerCase() === 'case.md') {
-    return toSlug(path.basename(path.dirname(outFile || '')) || name);
-  }
-
-  return toSlug(path.basename(outFile || '', '.md') || name);
-}
-
 // === SCAFFOLD EXECUTION ===
 // Creates a new case markdown file, respecting overwrite safety rules.
 export function runCaseScaffold(options = {}) {
   // Resolves working directory so script can be invoked from any location.
   const cwd = options.cwd || process.cwd();
-  // Reads desired output file path from options or uses default path.
-  const outFile = options.outFile || DEFAULT_OUTPUT;
   // Reads desired case display name from options or uses default title.
   const name = options.name || DEFAULT_NAME;
-  const caseSlug = resolveCaseSlugFromOutput(outFile, name);
+  const hasExplicitOutFile = typeof options.outFile === 'string' && options.outFile.trim().length > 0;
+
+  const defaultScaffold = hasExplicitOutFile
+    ? null
+    : resolveDefaultScaffoldValues(cwd, name);
+
+  // Reads desired output file path from options or uses resolved default path.
+  const outFile = hasExplicitOutFile
+    ? options.outFile
+    : (defaultScaffold?.outFile || DEFAULT_OUTPUT);
+
+  const caseSlug = hasExplicitOutFile
+    ? resolveCaseSlugFromOutput(outFile, name)
+    : defaultScaffold.slug;
+
+  const caseOrder = defaultScaffold?.caseOrder ?? DEFAULT_CASE_TEMPLATE.caseOrder;
   // Converts force option to explicit boolean for overwrite checks.
   const force = Boolean(options.force);
   // Resolves absolute output path to avoid relative path ambiguity.
@@ -428,7 +557,7 @@ export function runCaseScaffold(options = {}) {
   }
 
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.writeFileSync(outputPath, buildTemplate({ name, slug: caseSlug }), 'utf8');
+  fs.writeFileSync(outputPath, buildTemplate({ name, slug: caseSlug, caseOrder }), 'utf8');
   console.log(`[scaffold-case] Created starter case file: ${outputPath}`);
   return 0;
 }

package/templates/src/parser/markdown.js

@@ -10,7 +10,7 @@ import markdownItTaskLists from 'markdown-it-task-lists';
 // MARK: MARKDOWN RENDERER
 // Uses markdown-it + plugins to support broad markdown syntax for case content.
 const markdownRenderer = new MarkdownIt({
-  html: false,
+  html: true,
   linkify: true,
   typographer: true,
   breaks: false
@@ -56,6 +56,16 @@ markdownRenderer.renderer.rules.link_open = (tokens, idx, options, env, self) =>
   return self.renderToken(tokens, idx, options);
 };
 
+// Emits Mermaid fences as the Valence custom element instead of a code block.
+markdownRenderer.renderer.rules.fence = (tokens, idx) => {
+  const token = tokens[idx];
+  if (String(token.info || '').trim().split(/\s+/)[0].toLowerCase() !== 'mermaid') {
+    return `<pre><code>${markdownRenderer.utils.escapeHtml(token.content)}</code></pre>\n`;
+  }
+
+  return `<mermaid-diagram>${markdownRenderer.utils.escapeHtml(token.content)}</mermaid-diagram>\n`;
+};
+
 // MARK: VALIDATION CONTRACTS
 // Lists required scalar config fields that every case must define.
 const REQUIRED_SCALAR_FIELDS = ['id', 'thumbCategory', 'thumbBrand', 'thumbModel', 'thumbColor'];
@@ -107,6 +117,56 @@ function markdownToHtml(markdown) {
   return markdownRenderer.render(source);
 }
 
+// Renders localized markdown sections into HTML using the shared markdown-it pipeline.
+export function renderLocalizedMarkdownHtml(bodyText, localeCodes = DEFAULT_LOCALE_CODES) {
+  const normalizedBodyText = String(bodyText || '').replace(/<!--\s*config\s*[\s\S]*?-->/gi, '').trim();
+  const targetLocales = normalizeLocaleCodes(localeCodes);
+  const sections = Object.fromEntries(targetLocales.map((localeCode) => [localeCode, '']));
+  const markerLocales = new Set();
+  const langRegex = /<!--\s*lang:([a-z0-9-]+)\s*-->/gi;
+  let activeLang = null;
+  let lastIndex = 0;
+  let match;
+
+  while ((match = langRegex.exec(normalizedBodyText)) !== null) {
+    const markerLocale = String(match[1] || '').trim().toLowerCase();
+    if (!markerLocale) continue;
+    markerLocales.add(markerLocale);
+    if (!(markerLocale in sections)) {
+      sections[markerLocale] = '';
+    }
+
+    if (activeLang) {
+      sections[activeLang] += normalizedBodyText.slice(lastIndex, match.index);
+    }
+    activeLang = markerLocale;
+    lastIndex = langRegex.lastIndex;
+  }
+
+  if (activeLang) {
+    sections[activeLang] += normalizedBodyText.slice(lastIndex);
+  } else {
+    Object.keys(sections).forEach((localeCode) => {
+      sections[localeCode] = normalizedBodyText;
+    });
+  }
+
+  const resolvedLocales = normalizeLocaleCodes([...targetLocales, ...Object.keys(sections)]);
+  const htmlByLocale = Object.fromEntries(resolvedLocales.map((localeCode) => {
+    const sectionRaw = String(sections[localeCode] || '').trim();
+    return [localeCode, markdownToHtml(sectionRaw)];
+  }));
+
+  return {
+    htmlByLocale,
+    meta: {
+      localeCodes: resolvedLocales,
+      hasAnyLangMarker: markerLocales.size > 0,
+      hasLangMarkerByLocale: Object.fromEntries(resolvedLocales.map((localeCode) => [localeCode, markerLocales.has(localeCode)]))
+    }
+  };
+}
+
 // MARK: CONFIG BLOCK PARSING
 // Parses a top-level config JSON comment block and returns metadata + remaining body text.
 function parseConfigMetadata(rawText, contextLabel) {