domma-cms 0.25.16 → 0.30.0

package/scripts/migrate-docs.js

@@ -0,0 +1,280 @@
+/**
+ * One-shot porter: admin documentation screens → public page artefacts under
+ * the Domma Docs project. Reads each admin HTML template, strips the admin-only
+ * view header, wraps the body in page frontmatter tagged `project: domma-docs`,
+ * and writes content/pages/domma-docs/<path>.md. Re-runnable (overwrites).
+ *
+ * Run: node scripts/migrate-docs.js
+ */
+import {mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+
+const TPL = 'admin/js/templates/docs';
+const OUT = 'content/pages/domma-docs';
+const CUSTOM_CSS = 'content/custom.css';
+
+// Page chrome (hero, cards, grid, buttons) uses native Domma shortcode
+// components — see wrapPage() and the landing pages — so they get the framework's
+// own designs and effects. The only custom CSS we keep is whatever inline
+// <style> the templates carried (e.g. API method badges), collected below. Set
+// to '' so no hand-rolled layout CSS competes with Domma's components.
+// Only functional nav chrome (breadcrumb + prev/next bar) — Domma has no
+// Markdown breadcrumb component. Everything else (hero, cards, tabs, accordion,
+// buttons) is a native Domma component. Token-based so it follows the theme.
+const DOCS_BODY_CSS = `.doc-breadcrumb { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; max-width: 80ch; margin: 0 auto 1.25rem; font-size: .85rem; color: var(--dm-text-muted); }
+.doc-breadcrumb a { color: var(--dm-primary); text-decoration: none; }
+.doc-breadcrumb a:hover { text-decoration: underline; }
+.doc-breadcrumb [aria-current] { color: var(--dm-text); font-weight: 600; }
+.doc-pagenav { display: flex; flex-wrap: wrap; gap: .75rem; justify-content: space-between; align-items: center; max-width: 80ch; margin: 2.5rem auto 3rem; }
+.doc-pagenav .btn-secondary { margin-inline: auto; }
+.doc-nav { display: flex; flex-wrap: wrap; gap: .4rem; justify-content: center; max-width: 80ch; margin: 0 auto 1.75rem; padding: .5rem; border: 1px solid var(--dm-card-border, var(--dm-border)); border-radius: var(--dm-radius-lg, 14px); background: var(--dm-card-bg, var(--dm-surface)); }`;
+
+// Inline <style> blocks pulled out of the templates are accumulated here
+// (deduped) and written to custom.css with the base styles.
+const collectedStyles = new Set();
+
+// template basename → {path (URL tail = file path), title}
+const MAP = [
+    ['usage-pages',          'usage/pages',          'Pages'],
+    ['usage-media',          'usage/media',          'Media'],
+    ['usage-navigation',     'usage/navigation',     'Navigation'],
+    ['usage-dconfig',        'usage/dconfig',        'DConfig'],
+    ['usage-shortcodes',     'usage/shortcodes',     'Shortcodes'],
+    ['usage-site-settings',  'usage/site-settings',  'Site Settings'],
+    ['usage-plugins',        'usage/plugins',        'Plugins'],
+    ['usage-users-roles',    'usage/users-roles',    'Users & Roles'],
+    ['usage-views',          'usage/views',          'Views'],
+    ['usage-actions',        'usage/actions',        'Actions'],
+    ['usage-cta-shortcode',  'usage/cta-shortcode',  'CTA Shortcode'],
+    ['tutorial-crud',        'tutorials/crud',       'Building a CRUD App'],
+    ['tutorial-plugin',      'tutorials/plugin',     'Writing a Plugin'],
+    ['tutorial-forms',       'tutorials/forms',      'Form Follow-Up'],
+    ['components-reference', 'components',           'Components Reference'],
+    ['components-howto',     'components/howto',     'Components How-To'],
+    ['components-walkthrough','components/walkthrough','Components Walkthrough'],
+    ['components-rules',     'components/rules',     'Components Rules'],
+    ['api-authentication',   'api/authentication',   'Authentication'],
+    ['api-pages',            'api/pages',            'Pages API'],
+    ['api-settings',         'api/settings',         'Settings API'],
+    ['api-layouts',          'api/layouts',          'Layouts API'],
+    ['api-navigation',       'api/navigation',       'Navigation API'],
+    ['api-media',            'api/media',            'Media API'],
+    ['api-users',            'api/users',            'Users API'],
+    ['api-plugins',          'api/plugins',          'Plugins API'],
+    ['api-collections',      'api/collections',      'Collections API'],
+    ['api-views',            'api/views',            'Views API'],
+    ['api-actions',          'api/actions',          'Actions API']
+];
+
+// Drop the admin-only header block (<div class="view-header"> ... </div>).
+// The header contains no nested <div>, so a non-greedy match to the first
+// </div> is correct.
+function stripHeader(html) {
+    return html.replace(/<div class="view-header">[\s\S]*?<\/div>\s*/, '');
+}
+
+// The admin templates link with admin-SPA hash routes (#/…) and stale
+// /resources/… paths, none of which resolve on the public site. Rewrite them:
+// doc-to-doc links → public /domma-docs/… paths; admin-feature links → the
+// admin SPA (/admin#/…); resources links with a doc equivalent → that doc; the
+// rest of /resources/… (no equivalent) are unwrapped to plain text.
+const LINK_MAP = {
+    '#/docs/components-walkthrough': '/domma-docs/components/walkthrough',
+    '#/docs/components-rules':       '/domma-docs/components/rules',
+    '#/docs/components-howto':       '/domma-docs/components/howto',
+    '#/docs/components':             '/domma-docs/components',
+    '#/components':                  '/domma-docs/components',
+    '#/tutorials/plugin':            '/domma-docs/tutorials/plugin',
+    '#/tutorials/forms':             '/domma-docs/tutorials/forms',
+    '#/tutorials':                   '/domma-docs/tutorials',
+    '#/documentation':               '/domma-docs',
+    '#/actions':                     '/admin#/actions',
+    '#/collections':                 '/admin#/collections',
+    '#/forms':                       '/admin#/forms',
+    '#/plugins':                     '/admin#/plugins',
+    '#/settings':                    '/admin#/settings',
+    '/resources/shortcodes':         '/domma-docs/usage/shortcodes',
+    '/resources/components':         '/domma-docs/components'
+};
+function rewriteLinks(html) {
+    let out = html;
+    for (const [from, to] of Object.entries(LINK_MAP)) {
+        out = out.split(`href="${from}"`).join(`href="${to}"`);
+    }
+    // Any remaining /resources/… link has no doc equivalent — unwrap to text.
+    out = out.replace(/<a\b[^>]*\shref="\/resources\/[^"]*"[^>]*>([\s\S]*?)<\/a>/gi, '$1');
+    return out;
+}
+
+// Pull every inline <style> block out of the body (collecting its CSS for
+// custom.css) so no styling is lumped into the page content.
+function stripStyleBlocks(html) {
+    return html.replace(/<style\b[^>]*>([\s\S]*?)<\/style>\s*/gi, (_m, css) => {
+        const trimmed = css.trim();
+        if (trimmed) collectedStyles.add(trimmed);
+        return '';
+    });
+}
+
+// The admin templates are deeply indented. Markdown treats any line indented
+// 4+ spaces as a code block, which would render the structural HTML (tables,
+// divs, headings) as escaped source text. Strip leading indentation from every
+// line OUTSIDE <pre> blocks so each structural tag starts at column 0 and marked
+// passes it through as raw HTML. Inside <pre>, whitespace is significant (code
+// samples) and is preserved verbatim.
+function dedentOutsidePre(html) {
+    const parts = html.split(/(<pre\b[^>]*>[\s\S]*?<\/pre>)/gi);
+    return parts.map((part, i) =>
+        (i % 2 === 1) ? part : part.replace(/^[ \t]+/gm, '')
+    ).join('');
+}
+
+// Shortcode examples in the docs live inside <code>/<pre>. The render pipeline's
+// code-scrubber protects <pre> and backtick spans but NOT bare inline <code>,
+// so examples like [grid cols="N"]...[/grid] in table cells would be expanded
+// as real shortcodes. Escape square brackets inside every <pre> and <code>
+// region so all examples render literally on the public page.
+function escapeCodeBrackets(html) {
+    const esc = (region) => region.replace(/\[/g, '&#91;').replace(/\]/g, '&#93;');
+    html = html.replace(/<pre\b[^>]*>[\s\S]*?<\/pre>/gi, esc);   // <pre> first (incl. nested <code>)
+    html = html.replace(/<code\b[^>]*>[\s\S]*?<\/code>/gi, esc); // then standalone inline <code>
+    return html;
+}
+
+function frontmatter(title) {
+    return `---\ntitle: ${title}\nlayout: default\nstatus: published\nvisibility: public\nproject: domma-docs\n---\n\n`;
+}
+
+// The four top-level doc sections — rendered as a persistent nav on every page.
+const SECTIONS = [
+    {label: 'Usage',         href: '/domma-docs/usage'},
+    {label: 'Tutorials',     href: '/domma-docs/tutorials'},
+    {label: 'Components',    href: '/domma-docs/components'},
+    {label: 'API Reference', href: '/domma-docs/api'}
+];
+
+// Persistent section nav (Home + the four sections, current one highlighted).
+// Rendered just under the hero on every doc page so navigation is always present.
+function docNav(activeLabel) {
+    const links = [{label: 'Home', href: '/domma-docs'}, ...SECTIONS].map(s => {
+        const active = s.label === activeLabel;
+        return `<a class="btn btn-sm ${active ? 'btn-primary' : 'btn-ghost'}" href="${s.href}">${escText(s.label)}</a>`;
+    }).join('');
+    return `<nav class="doc-nav">${links}</nav>`;
+}
+
+// Section label + landing URL for the hero eyebrow, derived from the page path.
+function sectionFor(path) {
+    if (path.startsWith('usage/'))     return {label: 'Usage',         href: '/domma-docs/usage'};
+    if (path.startsWith('tutorials/')) return {label: 'Tutorials',     href: '/domma-docs/tutorials'};
+    if (path.startsWith('api/'))       return {label: 'API Reference', href: '/domma-docs/api'};
+    if (path === 'components' || path.startsWith('components/')) return {label: 'Components', href: '/domma-docs/components'};
+    return {label: 'Documentation', href: '/domma-docs'};
+}
+
+function heroAttr(s) {
+    return String(s).replace(/"/g, '&quot;');
+}
+function escText(s) {
+    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// Every template wraps its content in a consistent .row > .col-12 > .docs-body
+// shell (opening at the top, three closing </div> at the very end). Strip it to
+// get the bare inner content so we can split it into sections.
+function unwrapDocsBody(html) {
+    return html.trim()
+        .replace(/^<div class="row">\s*<div class="col-12">\s*<div class="docs-body">/, '')
+        .replace(/<\/div>\s*<\/div>\s*<\/div>\s*$/, '')
+        .trim();
+}
+
+// Plain-text heading title, safe to use as a shortcode attribute value.
+function headingText(inner) {
+    return inner.replace(/<[^>]+>/g, '')
+        .replace(/&amp;/g, '&').replace(/&mdash;/g, '—').replace(/&ndash;/g, '–')
+        .replace(/&quot;/g, "'").replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+        .replace(/\s+/g, ' ').trim().replace(/"/g, "'");
+}
+
+// Split inner content at top-level <hN> headings into {preamble, sections}.
+function splitSections(inner, level) {
+    const re = new RegExp(`<h${level}\\b[^>]*>([\\s\\S]*?)<\\/h${level}>`, 'gi');
+    const matches = [...inner.matchAll(re)];
+    if (!matches.length) return {preamble: inner, sections: []};
+    const preamble = inner.slice(0, matches[0].index).trim();
+    const sections = matches.map((m, i) => ({
+        title: headingText(m[1]),
+        body: inner.slice(m.index + m[0].length, i + 1 < matches.length ? matches[i + 1].index : inner.length).trim()
+    }));
+    return {preamble, sections};
+}
+
+// Turn the body into native Domma components. ≥7 sections → accordion (a long
+// scannable reference); 2–6 → tabs (first pane shown, rest a click away); <2 →
+// a single card. Any preamble before the first heading leads in its own card.
+function structureBody(body) {
+    const inner = unwrapDocsBody(body);
+    const level = /<h2\b/i.test(inner) ? 2 : 3;
+    const {preamble, sections} = splitSections(inner, level);
+    if (sections.length < 2) return `[card]\n${inner}\n[/card]`;
+    const lead = preamble ? `[card]\n${preamble}\n[/card]\n\n` : '';
+    if (sections.length <= 6) {
+        return lead + '[tabs]\n' +
+            sections.map(s => `[tab title="${s.title}"]\n${s.body}\n[/tab]`).join('\n') + '\n[/tabs]';
+    }
+    return lead + '[accordion multiple="true"]\n' +
+        sections.map(s => `[item title="${s.title}"]\n${s.body}\n[/item]`).join('\n') + '\n[/accordion]';
+}
+
+// Assemble a content page: full-width hero, breadcrumb, structured body, and a
+// prev / back-to-section / next nav bar (Domma .btn styles).
+function buildPage(section, title, body, prev, next) {
+    const hero = `[hero title="${heroAttr(title)}" tagline="${heroAttr(section.label)}" variant="gradient" align="center" fullwidth="true"][/hero]`;
+    const nav = docNav(section.label);
+    const crumb = `<nav class="doc-breadcrumb"><a href="/domma-docs">Docs</a><span>/</span>` +
+        `<a href="${section.href}">${escText(section.label)}</a><span>/</span>` +
+        `<span aria-current="page">${escText(title)}</span></nav>`;
+    const prevA = prev ? `<a class="btn btn-ghost" href="/domma-docs/${prev[1]}">← ${escText(prev[2])}</a>` : '<span></span>';
+    const nextA = next ? `<a class="btn btn-ghost" href="/domma-docs/${next[1]}">${escText(next[2])} →</a>` : '<span></span>';
+    const pagenav = `<nav class="doc-pagenav">${prevA}` +
+        `<a class="btn btn-secondary" href="${section.href}">All ${escText(section.label)}</a>${nextA}</nav>`;
+    return `${hero}\n\n${nav}\n\n${crumb}\n\n${structureBody(body)}\n\n${pagenav}`;
+}
+
+let n = 0;
+for (let i = 0; i < MAP.length; i++) {
+    const [tpl, path, title] = MAP[i];
+    const section = sectionFor(path);
+    const src  = readFileSync(join(TPL, `${tpl}.html`), 'utf8');
+    const body = escapeCodeBrackets(dedentOutsidePre(rewriteLinks(stripStyleBlocks(stripHeader(src))))).trim();
+    // prev / next are the section-mates either side of this page in MAP order.
+    const mates = MAP.filter(m => sectionFor(m[1]).label === section.label);
+    const mi = mates.findIndex(m => m[1] === path);
+    const prev = mi > 0 ? mates[mi - 1] : null;
+    const next = mi >= 0 && mi < mates.length - 1 ? mates[mi + 1] : null;
+    const dest = join(OUT, `${path}.md`);
+    mkdirSync(dirname(dest), {recursive: true});
+    writeFileSync(dest, frontmatter(title) + buildPage(section, title, body, prev, next) + '\n');
+    n++;
+}
+console.log(`[migrate-docs] wrote ${n} pages to ${OUT}`);
+
+// Write the docs CSS (base + extracted inline styles) into content/custom.css
+// as an idempotent managed block, so styling lives in the custom CSS file
+// rather than being lumped into the pages.
+const BEGIN = '/* >>> Domma Docs styles (managed by scripts/migrate-docs.js) — do not edit between markers >>> */';
+const END   = '/* <<< Domma Docs styles <<< */';
+const cssBody = [DOCS_BODY_CSS, ...collectedStyles].filter(Boolean).join('\n\n');
+const block = `${BEGIN}\n${cssBody}\n${END}`;
+
+let existing = '';
+try { existing = readFileSync(CUSTOM_CSS, 'utf8'); } catch { /* file may not exist */ }
+const blockRe = new RegExp(
+    BEGIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '[\\s\\S]*?' + END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+);
+const next = blockRe.test(existing)
+    ? existing.replace(blockRe, block)
+    : (existing.trim() ? existing.trimEnd() + '\n\n' : '') + block + '\n';
+writeFileSync(CUSTOM_CSS, next);
+console.log(`[migrate-docs] wrote docs CSS (${collectedStyles.size} extracted block(s) + base) to ${CUSTOM_CSS}`);