#!/usr/bin/env node
/**
* Generate the single-page Web Blender user manual.
*
* Usage:
* node tools/web/manual/generate-manual.mjs
*/
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const HERE = path.dirname(fileURLToPath(import.meta.url));
const REPO = path.resolve(HERE, "../../..");
const SOURCE = path.join(REPO, "user-manual/WEB_Blender_Web_Manual_20261113/manual.json");
const MATRIX = path.join(HERE, "feature-matrix.json");
const PUBLIC = path.join(REPO, "web/app/public");
const OUT = path.join(PUBLIC, "manuals");
const escapeHtml = (value) => String(value)
.replaceAll("&", "&").replaceAll("<", "<").replaceAll(">", ">")
.replaceAll('"', """).replaceAll("'", "'");
const manual = JSON.parse(fs.readFileSync(SOURCE, "utf8"));
const matrix = JSON.parse(fs.readFileSync(MATRIX, "utf8"));
const missing = [];
const existing = new Set();
function resolveImage(src) {
const file = src.startsWith("/") ? path.join(PUBLIC, src.slice(1)) : path.join(OUT, src);
if (!fs.existsSync(file)) missing.push(src);
return file;
}
function imageHtml(src, alt, caption) {
if (!src) return "";
resolveImage(src);
return `
${escapeHtml(caption ?? alt ?? "")}`;
}
const chapterById = new Map(manual.chapters.map((chapter) => [chapter.id, chapter]));
const navParts = manual.parts.map((part) => `
`).join("");
let figure = 0;
const chaptersHtml = manual.chapters.map((chapter) => {
const steps = chapter.steps.map((step, index) => {
const fig = step.image ? imageHtml(step.image, step.alt, `图 ${chapter.number}.${index + 1} ${step.title}`) : "";
const callout = step.callout ? `${escapeHtml(step.callout.text)}
` : "";
return `${index + 1}. ${escapeHtml(step.title)}
${escapeHtml(step.text)}
${callout}${fig}`;
}).join("");
const objectives = `${(chapter.objectives ?? []).map((item) => `- ${escapeHtml(item)}
`).join("")}
`;
const prereq = (chapter.prerequisites ?? []).length ? `前置:${chapter.prerequisites.map((id) => {
const target = chapterById.get(id);
return target ? `第 ${target.number} 章` : escapeHtml(id);
}).join("、")}
` : "";
const checks = (chapter.checks ?? []).length ? `完成检查
${chapter.checks.map((item) => `- ${escapeHtml(item)}
`).join("")}
` : "";
const tips = (chapter.tips ?? []).length ? `提示
${chapter.tips.map((item) => `- ${escapeHtml(item)}
`).join("")}
` : "";
const limits = (chapter.limits ?? []).filter(Boolean).length ? `限制 / 不支持
${chapter.limits.filter(Boolean).map((item) => `- ${escapeHtml(item)}
`).join("")}
` : "";
const links = (chapter.links ?? []).length ? `` : "";
const searchText = [chapter.title, chapter.summary, ...(chapter.objectives ?? []), ...chapter.steps.map((step) => `${step.title} ${step.text}`), ...(chapter.tips ?? []), ...(chapter.limits ?? [])].join(" ").toLowerCase();
return `
第 ${chapter.number} 章 · ${escapeHtml(chapter.level)} · ${escapeHtml(chapter.workspace)}
${escapeHtml(chapter.title)}
${escapeHtml(chapter.summary)}
${prereq}
本章目标
${objectives}
${steps}
${checks}${tips}${limits}${links}
`;
}).join("\n");
const supportRows = matrix.capabilities.map((item) => `| ${escapeHtml(item.area)} | ${escapeHtml(item.feature)} | ${escapeHtml(matrix.legend[item.status] ?? item.status)} | ${escapeHtml(item.note ?? "")} | ${item.chapter ? `${escapeHtml(item.chapter)}` : ""} |
`).join("");
const support = `附录 B:能力支持矩阵
${escapeHtml(matrix.legend.usable)};${escapeHtml(matrix.legend.partial)};${escapeHtml(matrix.legend["native-only"])};${escapeHtml(matrix.legend.unsupported)}。
`;
const appendixHtml = manual.appendices.map((appendix) => `${escapeHtml(appendix.title)}
${appendix.rows.map((row) => `${row.map((cell) => `| ${escapeHtml(cell)} | `).join("")}
`).join("")}
`).join("\n");
const html = `
${escapeHtml(manual.title)}
UM-${escapeHtml(manual.version)} · ${escapeHtml(manual.lastVerified)} · ${escapeHtml(manual.desktopVersion)}
${escapeHtml(manual.title)}
${escapeHtml(manual.intro)}
存储规则${manual.storagePolicy.rules.map((rule) => `- ${escapeHtml(rule)}
`).join("")}
${chaptersHtml}
${support}
${appendixHtml}
`;
const css = `:root{color-scheme:dark;--bg:#191b1a;--panel:#232624;--panel-2:#2b2f2c;--line:#414743;--text:#e7eae7;--muted:#a8b0a9;--accent:#79a98a;--accent-2:#d6b36a;--danger:#c9836f}
*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--bg);color:var(--text);font:15px/1.75 "Noto Sans SC",system-ui,-apple-system,"Segoe UI",sans-serif}a{color:#9bc7a9}
.manual-topbar{position:sticky;top:0;z-index:30;display:flex;align-items:center;gap:10px;flex-wrap:wrap;padding:8px 14px;background:#202321f2;border-bottom:1px solid var(--line);backdrop-filter:blur(6px)}
.manual-brand{font-weight:700;color:#eef3ee;text-decoration:none}.manual-menu-toggle{display:none;width:30px;height:28px;background:#343a35;color:#eee;border-radius:4px}
.manual-search{display:flex;align-items:center;gap:5px;flex:1 1 240px;max-width:520px;color:var(--muted);font-size:12px}.manual-search input{flex:1;min-width:0;padding:5px 8px;color:var(--text);background:#151716;border:1px solid #4d554f;border-radius:4px}
.manual-search-status{color:var(--accent-2);font-size:12px}.manual-topbar nav{display:flex;gap:12px;margin-left:auto;font-size:12px}.manual-topbar nav a{color:var(--muted);text-decoration:none}
.manual-layout{display:grid;grid-template-columns:300px minmax(0,1fr);align-items:start}.manual-sidebar{position:sticky;top:49px;max-height:calc(100vh - 49px);overflow:auto;padding:14px 10px;border-right:1px solid var(--line);background:#1e211f}
.manual-nav-group{margin-bottom:14px}.manual-nav-group>strong{display:block;margin:0 0 4px 7px;color:var(--accent-2);font-size:11px;letter-spacing:.08em}.manual-nav a{display:flex;gap:7px;padding:5px 8px;border-radius:4px;color:#cbd2cc;text-decoration:none;font-size:12px;line-height:1.35}.manual-nav a:hover{background:#2b302c}.manual-nav a span{flex:none;color:#8b9b8f;font-family:monospace}.manual-nav a[hidden]{display:none}.manual-nav a.active{background:#355343;color:#eaf3ec}
.manual-main{min-width:0;padding:24px clamp(16px,4vw,52px) 70px;overflow-wrap:anywhere}.manual-main p,.manual-main li{overflow-wrap:anywhere;word-break:break-word}.manual-hero{max-width:1050px;margin:0 auto 26px;padding:26px clamp(16px,3vw,30px);background:linear-gradient(135deg,#24302a,#242625 65%,#2f2a20);border:1px solid var(--line);border-radius:8px}.manual-kicker{color:var(--accent-2);font-size:12px;letter-spacing:.06em}.manual-hero h1{margin:6px 0 10px;font-size:clamp(28px,4vw,44px)}.manual-policy{margin-top:14px;padding:10px 14px;border-left:3px solid var(--accent-2);background:#292a25;font-size:13px}.manual-policy strong{color:#e6d1a4}.manual-policy ul{margin:4px 0 0;padding-left:18px}
.manual-chapter,.manual-appendix{max-width:1050px;margin:0 auto 28px;padding:22px clamp(16px,3vw,30px);background:var(--panel);border:1px solid var(--line);border-radius:8px}.manual-chapter h2,.manual-appendix h2{margin:4px 0 8px;line-height:1.3}.manual-chapter-kicker{margin:0;color:var(--accent-2);font-size:11px;letter-spacing:.06em}.manual-summary{color:#cdd4ce}.manual-meta{color:var(--muted);font-size:12px}
.manual-block{margin:16px 0}.manual-block h3{margin:0 0 5px;font-size:14px;color:#cfe0d4}.manual-block ul{margin:0;padding-left:20px}.manual-limit{border-left:3px solid var(--danger);padding-left:12px}
.manual-steps{margin:18px 0 0;padding:0;list-style:none;counter-reset:step}.manual-steps>li{position:relative;margin:0 0 24px;padding:0 0 0 38px}.manual-steps>li::before{counter-increment:step;content:counter(step);position:absolute;left:0;top:0;display:grid;place-items:center;width:26px;height:26px;border-radius:50%;background:#355343;color:#e8f2ec;font-size:12px;font-weight:700}.manual-steps h3{margin:2px 0 6px;font-size:14px;color:#e6ece7}.manual-steps p{margin:0 0 8px}
figure{margin:10px 0 0}.manual-steps img{display:block;width:100%;height:auto;border:1px solid var(--line);border-radius:6px;background:#111}figcaption{margin-top:5px;color:#8f9a92;font-size:11px}
.manual-callout{margin:8px 0;padding:8px 11px;background:#2c302a;border-left:3px solid var(--accent);border-radius:3px}.manual-callout.limit{border-left-color:var(--danger)}.manual-callout.warning{border-left-color:var(--accent-2)}
.manual-chapter-nav{display:flex;justify-content:space-between;margin-top:20px;padding-top:10px;border-top:1px solid var(--line);font-size:12px}.manual-chapter-nav a{color:var(--accent);text-decoration:none}
.manual-table-wrap{width:100%;max-width:100%;overflow-x:auto}.manual-table-wrap table{width:100%;table-layout:fixed;border-collapse:collapse;font-size:12px}.manual-table-wrap td,.manual-table-wrap th{padding:6px 8px;text-align:left;border:1px solid #454c47;vertical-align:top;overflow-wrap:anywhere;word-break:break-word}.manual-table-wrap th{background:#313732}.status{padding:1px 6px;border-radius:8px;font-size:10px;white-space:nowrap}.status.usable{background:#2f513d;color:#d8f0de}.status.partial{background:#514a2d;color:#f1e1ae}.status.native-only{background:#3b4554;color:#d7e3f5}.status.unsupported{background:#4c3331;color:#f1d4ce}
.manual-footer{max-width:1050px;margin:20px auto 0;padding-top:14px;border-top:1px solid var(--line);color:#8f9a92;font-size:11px}
@media(max-width:900px){.manual-topbar nav{display:none}.manual-menu-toggle{display:block}.manual-layout{grid-template-columns:1fr}.manual-sidebar{position:fixed;left:0;top:49px;bottom:0;z-index:25;width:280px;transform:translateX(-100%);transition:transform .15s}.manual-sidebar.open{transform:none;box-shadow:20px 0 40px #0008}.manual-main{padding-top:14px}}
@media print{.manual-topbar,.manual-sidebar,.manual-menu-toggle,.manual-chapter-nav,.manual-search-status{display:none!important}.manual-layout{display:block}.manual-main{padding:0}.manual-chapter,.manual-appendix{break-inside:avoid;border:0;padding:0;margin:0 0 18px}.manual-hero{break-after:page}figure img{max-height:420px;object-fit:contain} }
`;
const js = `(() => {
const sidebar = document.querySelector('.manual-sidebar');
const toggle = document.querySelector('.manual-menu-toggle');
const search = document.querySelector('.manual-search input');
const status = document.querySelector('.manual-search-status');
const links = Array.from(document.querySelectorAll('.manual-nav a[data-nav-id]'));
const articles = Array.from(document.querySelectorAll('.manual-chapter'));
const apply = () => {
const query = (search?.value || '').trim().toLowerCase();
let matches = 0;
for (const link of links) {
const article = document.querySelector('#' + CSS.escape(link.dataset.navId));
const text = (article?.dataset.search || link.textContent || '').toLowerCase();
const hit = !query || text.includes(query) || (link.textContent || '').toLowerCase().includes(query);
link.hidden = !hit;
if (hit) matches += 1;
}
for (const article of articles) {
const text = (article.dataset.search || '').toLowerCase();
article.hidden = Boolean(query) && !text.includes(query);
}
if (status) status.textContent = query ? matches + ' 个匹配' : '';
};
search?.addEventListener('input', apply);
toggle?.addEventListener('click', () => sidebar?.classList.toggle('open'));
window.addEventListener('keydown', (event) => {
if (event.key === '/' && document.activeElement !== search) { event.preventDefault(); search?.focus(); }
if (event.key === 'Escape' && search) { search.value = ''; apply(); search.blur(); }
});
const observer = 'IntersectionObserver' in window ? new IntersectionObserver((entries) => {
for (const entry of entries) {
if (!entry.isIntersecting) continue;
const id = entry.target.id;
for (const link of links) link.classList.toggle('active', link.dataset.navId === id);
}
}, { rootMargin: '-30% 0px -60% 0px' }) : null;
for (const article of articles) observer?.observe(article);
})();
`;
fs.mkdirSync(OUT, { recursive: true });
fs.mkdirSync(path.join(OUT, "images"), { recursive: true });
fs.writeFileSync(path.join(OUT, "index.html"), html, "utf8");
fs.writeFileSync(path.join(OUT, "manual.css"), css, "utf8");
fs.writeFileSync(path.join(OUT, "manual.js"), js, "utf8");
fs.writeFileSync(path.join(OUT, "manual-search.json"), JSON.stringify({ schemaVersion: 1, chapters: manual.chapters.map((chapter) => ({ id: chapter.id, title: chapter.title, summary: chapter.summary })) }, null, 2) + "\n", "utf8");
const manifest = { schemaVersion: 1, generatedAt: new Date().toISOString(), version: manual.version, lastVerified: manual.lastVerified, sourceCommit: manual.sourceCommit, images: [...new Set(manual.chapters.flatMap((chapter) => chapter.steps.map((step) => step.image).filter(Boolean)))].map((src) => ({ src, file: src.startsWith("/") ? src : `/${src}`, exists: existing.has(src) || fs.existsSync(src.startsWith("/") ? path.join(PUBLIC, src.slice(1)) : path.join(OUT, src)) })) };
fs.writeFileSync(path.join(OUT, "images", "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf8");
console.log(JSON.stringify({ status: missing.length ? "MISSING_ASSETS" : "PASS", chapters: manual.chapters.length, appendices: manual.appendices.length, missing, output: path.join(OUT, "index.html") }, null, 2));
if (missing.length) process.exitCode = 1;