diff --git a/app/export-runner.js b/app/export-runner.js
new file mode 100644
index 0000000..17f65b8
--- /dev/null
+++ b/app/export-runner.js
@@ -0,0 +1,42 @@
+'use strict';
+
+const path = require('node:path');
+const { fork } = require('node:child_process');
+
+const WORKER_PATH = path.join(__dirname, '..', 'core', 'export-worker.js');
+
+/**
+ * Run an export job in a forked helper process, so building the render AST
+ * and rendering the output (e.g. a multi-step PDF) never blocks the main
+ * process — and therefore never freezes the editor window — no matter how
+ * large the guide is.
+ */
+function runExportInWorker({ dataDir, guideId, format, options, outDir, globals, maxSteps }) {
+ return new Promise((resolve, reject) => {
+ const worker = fork(WORKER_PATH, [], {
+ env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+ });
+
+ let settled = false;
+ const finish = (fn, value) => {
+ if (settled) return;
+ settled = true;
+ worker.removeAllListeners();
+ worker.kill();
+ fn(value);
+ };
+
+ worker.once('message', (msg) => {
+ if (msg && msg.ok) finish(resolve, msg.result);
+ else finish(reject, new Error((msg && msg.error) || 'Export worker failed.'));
+ });
+ worker.once('error', (err) => finish(reject, err));
+ worker.once('exit', (code) => {
+ finish(reject, new Error(`Export worker exited unexpectedly (code ${code}).`));
+ });
+
+ worker.send({ dataDir, guideId, format, options, outDir, globals, maxSteps });
+ });
+}
+
+module.exports = { runExportInWorker };
diff --git a/app/main.js b/app/main.js
index b383010..3dc4bbf 100644
--- a/app/main.js
+++ b/app/main.js
@@ -11,9 +11,10 @@ const {
const { GuideStore } = require('../core/store');
const { Settings } = require('../core/settings');
const { SearchIndex } = require('../core/search');
-const { TemplateManager, FORMATS } = require('../core/templates');
+const { TemplateManager, FORMATS, FORMAT_LABELS } = require('../core/templates');
const { buildRenderAst } = require('../core/renderast');
const { runExport, EXPORTERS } = require('../exporters');
+const { runExportInWorker } = require('./export-runner');
const { exportGuideArchive, importGuideArchive, saveLinkedGuide, readArchive } = require('../core/archive');
const { createSnapshot, listSnapshots, restoreSnapshot } = require('../core/snapshots');
const { readLock } = require('../core/locks');
@@ -578,13 +579,17 @@ function setupIpc() {
});
// export + preview
- h('export:formats', () => FORMATS.filter((f) => EXPORTERS[f]));
+ h('export:formats', () => FORMATS.filter((f) => EXPORTERS[f]).map((format) => ({
+ id: format,
+ label: FORMAT_LABELS[format] || format,
+ })));
h('export:defaults', ({ format }) => {
// Exporter modules expose DEFAULT_TEMPLATE; the dialog renders editable
// options from it (booleans -> checkbox, numbers -> number, strings -> text).
const mod = {
json: '../exporters/json',
markdown: '../exporters/markdown',
+ wikijs: '../exporters/wikijs',
'html-simple': '../exporters/html',
'html-rich': '../exporters/html',
confluence: '../exporters/confluence',
@@ -607,8 +612,14 @@ function setupIpc() {
dir = res.filePaths[0];
}
settings.set(`exports.lastOutputDirs.${format}`, dir);
- const ast = buildRenderAst(store, guideId, { globals: settings.getGlobalPlaceholders() });
- const result = runExport(format, ast, dir, options || {});
+ const result = await runExportInWorker({
+ dataDir: store.root,
+ guideId,
+ format,
+ options: options || {},
+ outDir: dir,
+ globals: settings.getGlobalPlaceholders(),
+ });
if (settings.get('exports.openFolderAfterExport')) shell.showItemInFolder(result.file);
return { ok: true, ...result };
});
diff --git a/app/renderer/app.js b/app/renderer/app.js
index 96376cd..1692691 100644
--- a/app/renderer/app.js
+++ b/app/renderer/app.js
@@ -317,6 +317,7 @@ class StepForgeApp {
const rect = e.target.getBoundingClientRect();
contextMenu(rect.left, rect.bottom + 4, [
{ label: 'Rename guide…', action: () => this.renameGuide() },
+ { label: 'Guide information…', action: () => this.editor.openGuideInfo() },
{ label: 'Guide placeholders…', action: () => this.editor.openGuidePlaceholders() },
{ label: 'Backups & snapshots…', action: () => this.editor.openBackupsDialog() },
{ label: guide && guide.linkedSource ? 'Linked guide…' : 'Linked guide (not linked)', action: () => this.editor.openLinkedGuide() },
diff --git a/app/renderer/dialogs.js b/app/renderer/dialogs.js
index 532a64e..de99f9d 100644
--- a/app/renderer/dialogs.js
+++ b/app/renderer/dialogs.js
@@ -413,28 +413,43 @@ function showExportDialog({
outDir: outDirInput.value.trim() || null,
});
+ const cancelBtn = el('button', { onClick: () => { close(); resolve(false); } }, 'Cancel');
+ const previewBtn = el('button', {
+ onClick: async () => {
+ if (typeof onPreview !== 'function') return;
+ setButtonLoading(previewBtn, true, 'Preview…');
+ try {
+ await onPreview(payload()); // keep dialog open so settings can be tweaked
+ } finally {
+ setButtonLoading(previewBtn, false);
+ }
+ },
+ }, 'Preview');
+ const exportBtn = el('button.primary', {
+ onClick: async () => {
+ if (typeof onExport !== 'function') return;
+ cancelBtn.disabled = true;
+ previewBtn.disabled = true;
+ setButtonLoading(exportBtn, true, 'Exporting…');
+ try {
+ const ok = await onExport(payload());
+ if (ok !== false) {
+ close();
+ resolve(true);
+ return;
+ }
+ } finally {
+ cancelBtn.disabled = false;
+ previewBtn.disabled = false;
+ setButtonLoading(exportBtn, false);
+ }
+ },
+ }, 'Export');
+
const { close } = openModal({
title: 'Export',
body,
- footer: [
- el('button', { onClick: () => { close(); resolve(false); } }, 'Cancel'),
- el('button', {
- onClick: async () => {
- if (typeof onPreview !== 'function') return;
- await onPreview(payload()); // keep dialog open so settings can be tweaked
- },
- }, 'Preview'),
- el('button.primary', {
- onClick: async () => {
- if (typeof onExport !== 'function') return;
- const ok = await onExport(payload());
- if (ok !== false) {
- close();
- resolve(true);
- }
- },
- }, 'Export'),
- ],
+ footer: [cancelBtn, previewBtn, exportBtn],
wide: true,
onClose: () => resolve(false),
});
@@ -639,6 +654,53 @@ function showPlaceholdersDialog({ title = 'Placeholders', hint = '', values = {}
});
}
+/**
+ * Optional document metadata (author, co-authors, organization, description)
+ * shown at the top of the guide, below the title, and surfaced on the PDF
+ * cover page and the top of other export formats.
+ */
+function showGuideInfoDialog({ values = {}, onSave } = {}) {
+ return new Promise((resolve) => {
+ const authorInput = makeInput(values.author || '', 'text', { placeholder: 'e.g. Jane Doe' });
+ const coAuthorsInput = makeInput(values.coAuthors || '', 'text', { placeholder: 'e.g. Alex Lee, Sam Patel' });
+ const organizationInput = makeInput(values.organization || '', 'text', { placeholder: 'e.g. Acme Corp' });
+ const descriptionInput = el('textarea', {
+ rows: 4,
+ placeholder: 'A short summary of this guide.',
+ }, values.description || '');
+
+ const { close } = openModal({
+ title: 'Guide information',
+ body: el('div', {},
+ el('div.muted', { style: { marginBottom: '10px' } },
+ 'All fields are optional. They appear below the title on the guide and on the PDF cover page.'),
+ labeledRow('Author', authorInput),
+ labeledRow('Co-authors', coAuthorsInput),
+ labeledRow('Organization', organizationInput),
+ labeledRow('Description', descriptionInput, { stacked: true }),
+ el('div.muted', { style: { marginTop: '-4px' } },
+ 'Shown on the first page of the PDF and at the top of other export formats.'),
+ ),
+ footer: [
+ el('button', { onClick: () => { close(); resolve(false); } }, 'Cancel'),
+ el('button.primary', {
+ onClick: async () => {
+ await onSave?.({
+ author: authorInput.value.trim(),
+ coAuthors: coAuthorsInput.value.trim(),
+ organization: organizationInput.value.trim(),
+ description: descriptionInput.value.trim(),
+ });
+ close();
+ resolve(true);
+ },
+ }, 'Save'),
+ ],
+ onClose: () => resolve(false),
+ });
+ });
+}
+
const SHORTCUTS = [
['Capture & steps', [
['Ctrl+S', 'Save (writes linked archive when guide is linked)'],
@@ -727,6 +789,7 @@ window.StepForgeDialogs = {
showInfoDialog,
showBackupsDialog,
showPlaceholdersDialog,
+ showGuideInfoDialog,
showShortcutsDialog,
showTemplateManager,
showRecordingReminder,
diff --git a/app/renderer/editor.js b/app/renderer/editor.js
index b6ab0e6..840f252 100644
--- a/app/renderer/editor.js
+++ b/app/renderer/editor.js
@@ -87,6 +87,16 @@ function stepNumberMap(steps) {
return numbers;
}
+function stepDepth(step, stepMap) {
+ let depth = 0;
+ let parent = step.parentStepId;
+ while (parent && stepMap.has(parent)) {
+ depth += 1;
+ parent = stepMap.get(parent).parentStepId;
+ }
+ return depth;
+}
+
function isEditableTarget(target) {
return target && (
target.tagName === 'INPUT' ||
@@ -761,15 +771,10 @@ class GuideEditor {
this.dom.selectStepsBtn.className = this.stepSelectMode ? 'primary' : '';
for (const step of this.steps) {
const number = numbers.get(step.stepId) || '';
- let depth = 0;
- let parent = step.parentStepId;
- while (parent && this.stepMap.has(parent)) {
- depth += 1;
- parent = this.stepMap.get(parent).parentStepId;
- }
+ const depth = stepDepth(step, this.stepMap);
const selected = current && current.stepId === step.stepId;
const checked = this.selectedSteps.has(step.stepId);
- const item = el('div.step-item', {
+ const itemProps = {
className: `step-item${selected ? ' selected' : ''}${depth ? ' sub' : ''}${step.skipped ? ' skipped' : ''}${step.hidden ? ' hiddenstep' : ''}`,
dataset: { stepId: step.stepId },
onClick: () => {
@@ -802,23 +807,26 @@ class GuideEditor {
{ label: 'Delete step', danger: true, action: () => this.deleteSelectedStep() },
]);
},
- },
- this.stepSelectMode
- ? el('input', {
- type: 'checkbox',
- checked,
- onClick: (e) => e.stopPropagation(),
- onChange: () => this.toggleStepSelection(step.stepId),
- })
- : null,
- el('span.status-dot', { className: `status-dot status-${step.status}` }),
- el('span.num', {}, number || '•'),
- el('span.t', {}, step.title || 'Untitled step'),
- el('span.flags', {}, [
- step.parentStepId ? 'sub' : '',
- step.hidden ? 'hidden' : '',
- step.skipped ? 'skipped' : '',
- ].filter(Boolean).join(' · ')));
+ };
+ if (depth) itemProps.style = { marginLeft: `${depth * 18}px` };
+ const item = el('div.step-item', itemProps,
+ this.stepSelectMode
+ ? el('input', {
+ type: 'checkbox',
+ checked,
+ onClick: (e) => e.stopPropagation(),
+ onChange: () => this.toggleStepSelection(step.stepId),
+ })
+ : null,
+ el('span.status-dot', { className: `status-dot status-${step.status}` }),
+ el('span.num', {}, number || '•'),
+ el('span.t', {}, step.title || 'Untitled step'),
+ el('span.flags', {}, [
+ step.parentStepId ? 'sub' : '',
+ step.hidden ? 'hidden' : '',
+ step.skipped ? 'skipped' : '',
+ ].filter(Boolean).join(' · ')),
+ );
this.dom.stepsList.append(item);
}
if (!this.steps.length) {
@@ -1571,6 +1579,22 @@ class GuideEditor {
});
}
+ async openGuideInfo() {
+ if (!this.guide) return;
+ await dialogs.showGuideInfoDialog({
+ values: {
+ ...this.guide.metadata,
+ description: htmlToPlainText(this.guide.descriptionHtml || ''),
+ },
+ onSave: async ({ description, ...metadata }) => {
+ this.guide.metadata = metadata;
+ this.guide.descriptionHtml = textToHtml(description);
+ await api.guide.save({ guide: this.guide });
+ this.onToast('Guide information saved.');
+ },
+ });
+ }
+
openShortcutsHelp() {
dialogs.showShortcutsDialog();
}
@@ -1642,7 +1666,11 @@ class GuideEditor {
}
async openExportDialog() {
- const formats = (await api.export.formats()).map((id) => ({ id, label: id.replace(/-/g, ' ') }));
+ const formats = (await api.export.formats()).map((format) => (
+ typeof format === 'string'
+ ? { id: format, label: format.replace(/-/g, ' ') }
+ : format
+ ));
const templatesByFormat = {};
for (const format of formats) {
templatesByFormat[format.id] = await api.templates.list({ format: format.id });
diff --git a/app/renderer/style.css b/app/renderer/style.css
index 06f6675..f0bda60 100644
--- a/app/renderer/style.css
+++ b/app/renderer/style.css
@@ -90,6 +90,25 @@ button.tool.active {
border-color: var(--accent);
color: var(--accent-fg);
}
+button:disabled { opacity: 0.6; cursor: default; }
+button.loading {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ gap: 7px;
+}
+
+.spinner {
+ display: inline-block;
+ width: 13px;
+ height: 13px;
+ border: 2px solid currentColor;
+ border-top-color: transparent;
+ border-radius: 50%;
+ opacity: 0.85;
+ animation: spin 0.7s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
input, select, textarea {
font: inherit;
diff --git a/app/renderer/util.js b/app/renderer/util.js
index c521fe7..dc70189 100644
--- a/app/renderer/util.js
+++ b/app/renderer/util.js
@@ -34,6 +34,27 @@ function clearNode(node) {
while (node.firstChild) node.removeChild(node.firstChild);
}
+/**
+ * Toggle a button into/out of a busy state: disables it and swaps its label
+ * for a spinner + `label` (e.g. "Exporting…"), restoring the original label
+ * afterwards. Used for actions that block on a slow main-process call.
+ */
+function setButtonLoading(btn, loading, label) {
+ if (loading) {
+ if (btn.dataset.origLabel === undefined) btn.dataset.origLabel = btn.textContent;
+ btn.disabled = true;
+ btn.classList.add('loading');
+ clearNode(btn);
+ btn.append(el('span.spinner'), label || btn.dataset.origLabel);
+ } else {
+ btn.disabled = false;
+ btn.classList.remove('loading');
+ clearNode(btn);
+ btn.append(btn.dataset.origLabel ?? '');
+ delete btn.dataset.origLabel;
+ }
+}
+
function debounce(fn, ms) {
let t = null;
const wrapped = (...args) => {
@@ -187,3 +208,21 @@ function fmtDate(iso) {
const escapeHtml = (s) => String(s ?? '')
.replace(/&/g, '&').replace(//g, '>').replace(/"/g, '"');
+
+/** Inverse of textToHtml, for loading sanitized description HTML into a plain textarea. */
+function htmlToPlainText(html) {
+ return String(html || '')
+ .replace(/<(br|\/p|\/div|\/li|\/h[1-6])\s*\/?>/gi, '\n')
+ .replace(/<[^>]*>/g, '')
+ .replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, '\'').replace(/&/g, '&')
+ .replace(/[ \t]+/g, ' ').replace(/\s*\n\s*/g, '\n').trim();
+}
+
+/** Plain textarea text -> sanitizer-allowed paragraph HTML (blank line = new paragraph). */
+function textToHtml(text) {
+ const trimmed = String(text || '').trim();
+ if (!trimmed) return '';
+ return trimmed.split(/\n{2,}/)
+ .map((para) => `${escapeHtml(para).replace(/\n/g, '
')}
`)
+ .join('');
+}
diff --git a/core/export-worker.js b/core/export-worker.js
new file mode 100644
index 0000000..b19d174
--- /dev/null
+++ b/core/export-worker.js
@@ -0,0 +1,26 @@
+'use strict';
+
+const { GuideStore } = require('./store');
+const { buildRenderAst } = require('./renderast');
+const { runExport } = require('../exporters');
+
+/**
+ * Entry point for the export helper process (forked via
+ * app/export-runner.js). Runs one export job — building the render AST and
+ * invoking the exporter — off the main process so a large guide's PDF/DOCX/
+ * etc. rendering never blocks the UI.
+ */
+
+process.on('message', (job) => {
+ let payload;
+ try {
+ const { dataDir, guideId, format, options, outDir, globals, maxSteps } = job;
+ const store = new GuideStore(dataDir);
+ const ast = buildRenderAst(store, guideId, { globals, maxSteps });
+ const result = runExport(format, ast, outDir, options || {});
+ payload = { ok: true, result };
+ } catch (err) {
+ payload = { ok: false, error: err && err.message ? err.message : String(err) };
+ }
+ process.send(payload, () => process.exit(payload.ok ? 0 : 1));
+});
diff --git a/core/pdf.js b/core/pdf.js
index 21febb7..04ceefb 100644
--- a/core/pdf.js
+++ b/core/pdf.js
@@ -60,6 +60,7 @@ class PdfBuilder {
this.images = []; // { name, width, height, data (deflated RGB), smask? }
this.imageCache = new Map();
this.bookmarks = []; // { title, pageIndex, y }
+ this.links = []; // { pageIndex, x, yTop, w, h, target }
}
addPage() {
@@ -173,6 +174,16 @@ class PdfBuilder {
this.bookmarks.push({ title: toLatin1(title), pageIndex });
}
+ /**
+ * Add a clickable region that jumps to another page (e.g. a Contents
+ * entry linking to a step). `target` is either a page index, or an
+ * object whose `pageIndex` is filled in later — once the destination
+ * page is known — and read when `build()` runs.
+ */
+ linkRect(x, yTop, w, h, target, pageIndex = this.pages.length - 1) {
+ this.links.push({ pageIndex, x, yTop, w, h, target });
+ }
+
build() {
if (!this.pages.length) this.addPage();
const objects = []; // 1-based; objects[i] = body string|Buffer after header
@@ -212,6 +223,27 @@ class PdfBuilder {
));
}
+ // Link annotations (e.g. clickable Contents entries that jump to a
+ // step's page). Targets resolved late, after every step has claimed a
+ // page, so `target` may be an object whose `pageIndex` was only just set.
+ const pageAnnots = new Map(); // page index -> [annotation object id, ...]
+ for (const link of this.links) {
+ const targetIndex = typeof link.target === 'number' ? link.target : link.target?.pageIndex;
+ if (targetIndex == null || !pageIds[targetIndex]) continue;
+ const y1 = this.pageHeight - link.yTop - link.h;
+ const y2 = this.pageHeight - link.yTop;
+ const annotId = addObj(
+ `<< /Type /Annot /Subtype /Link /Rect [${link.x.toFixed(2)} ${y1.toFixed(2)} ${(link.x + link.w).toFixed(2)} ${y2.toFixed(2)}] ` +
+ `/Border [0 0 0] /Dest [${pageIds[targetIndex]} 0 R /Fit] >>`
+ );
+ if (!pageAnnots.has(link.pageIndex)) pageAnnots.set(link.pageIndex, []);
+ pageAnnots.get(link.pageIndex).push(annotId);
+ }
+ for (const [pageIndex, annotIds] of pageAnnots) {
+ const id = pageIds[pageIndex];
+ objects[id - 1] = objects[id - 1].replace(/ >>$/, ` /Annots [${annotIds.map((a) => `${a} 0 R`).join(' ')}] >>`);
+ }
+
let outlinesRef = '';
if (this.bookmarks.length) {
const outlineRootId = objects.length + 1;
diff --git a/core/renderast.js b/core/renderast.js
index 773f583..fe0dd64 100644
--- a/core/renderast.js
+++ b/core/renderast.js
@@ -125,6 +125,11 @@ function buildRenderAst(store, guideId, { globals = {}, now = new Date(), maxSte
createdAt: guide.createdAt,
updatedAt: guide.updatedAt,
flags: guide.flags,
+ metadata: {
+ author: expand(guide.metadata?.author || ''),
+ coAuthors: expand(guide.metadata?.coAuthors || ''),
+ organization: expand(guide.metadata?.organization || ''),
+ },
},
steps: limited,
};
diff --git a/core/schema.js b/core/schema.js
index 84cd151..88e2b51 100644
--- a/core/schema.js
+++ b/core/schema.js
@@ -34,6 +34,12 @@ function createGuide(fields = {}) {
title: fields.title || 'Untitled guide',
descriptionHtml: sanitizeHtml(fields.descriptionHtml || ''),
placeholders: { ...(fields.placeholders || {}) },
+ metadata: {
+ author: '',
+ coAuthors: '',
+ organization: '',
+ ...(fields.metadata || {}),
+ },
flags: {
focusedViewDefault: false,
hideSkippedStepsInExports: true,
@@ -149,6 +155,7 @@ function validateGuide(guide) {
if (!Array.isArray(guide.stepsOrder)) errors.push('stepsOrder must be an array');
else if (new Set(guide.stepsOrder).size !== guide.stepsOrder.length) errors.push('stepsOrder has duplicates');
if (guide.placeholders && typeof guide.placeholders !== 'object') errors.push('placeholders must be an object');
+ if (guide.metadata && typeof guide.metadata !== 'object') errors.push('metadata must be an object');
if (errors.length) throw new Error(`invalid guide: ${errors.join('; ')}`);
return guide;
}
diff --git a/core/templates.js b/core/templates.js
index 1422383..225c884 100644
--- a/core/templates.js
+++ b/core/templates.js
@@ -11,7 +11,21 @@ const { writeJsonSync, readJsonSync, atomicWriteFileSync, nowIso } = require('./
* defaults, shareable as .sfglt zip files.
*/
-const FORMATS = ['json', 'markdown', 'html-simple', 'html-rich', 'confluence', 'pdf', 'gif', 'image-bundle', 'docx', 'pptx'];
+const FORMATS = ['json', 'markdown', 'wikijs', 'html-simple', 'html-rich', 'confluence', 'pdf', 'gif', 'image-bundle', 'docx', 'pptx'];
+
+const FORMAT_LABELS = {
+ json: 'JSON',
+ markdown: 'Markdown',
+ wikijs: 'Wiki.js',
+ 'html-simple': 'HTML (simple)',
+ 'html-rich': 'HTML (rich)',
+ confluence: 'Confluence',
+ pdf: 'PDF',
+ gif: 'GIF',
+ 'image-bundle': 'Image bundle',
+ docx: 'DOCX',
+ pptx: 'PPTX',
+};
class TemplateManager {
constructor(templatesDir) {
@@ -96,4 +110,4 @@ class TemplateManager {
}
}
-module.exports = { TemplateManager, FORMATS };
+module.exports = { TemplateManager, FORMATS, FORMAT_LABELS };
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 1ea0578..095560c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -81,6 +81,7 @@ guide.json + step.json + settings
▼ hidden/skipped, focused-view geometry)
Render AST ──► exporters/json.js .json + steps-/ images
──► exporters/markdown.js .md + steps-<title>/ images
+ ──► exporters/wikijs.js .md + steps-<title>/ images
──► exporters/html-simple.js single self-contained .html
──► exporters/html-rich.js checkboxes + floating TOC
──► exporters/pdf.js native PDF writer (core/pdf.js)
diff --git a/exporters/confluence.js b/exporters/confluence.js
index 2f00a76..675ef15 100644
--- a/exporters/confluence.js
+++ b/exporters/confluence.js
@@ -5,6 +5,7 @@ const path = require('node:path');
const { slugify, escapeXml } = require('../core/util');
const { encodePng } = require('../core/png');
const { guideSlug, renderAllImages, stepContentGroups, codeBlockText } = require('./common');
+const { anchorFor, guideMetaLines, guideSummary } = require('./document-layout');
/**
* Confluence storage-format export. Writes a single XHTML document plus a
@@ -14,6 +15,7 @@ const { guideSlug, renderAllImages, stepContentGroups, codeBlockText } = require
const DEFAULT_TEMPLATE = {
includeImages: true,
+ toc: true,
};
const MACRO_FOR_LEVEL = {
@@ -23,10 +25,6 @@ const MACRO_FOR_LEVEL = {
success: 'tip',
};
-function anchorFor(step) {
- return `step-${step.number.replace(/\./g, '-')}`;
-}
-
function stepLinkRewrite(html, ast) {
return String(html || '').replace(/href="step:([^"]+)"/g, (m, id) => {
const target = ast.steps.find((s) => s.stepId === id);
@@ -112,7 +110,11 @@ function exportConfluence(ast, outDir, template = {}) {
</head>
<body>
<h1>${escapeXml(ast.guide.title)}</h1>
+ <div style="border-bottom: 4px solid #2563eb; margin: 14px 0 18px;"></div>
+ ${guideMetaLines(ast).map((line) => `<p><strong>${escapeXml(line.split(': ')[0])}:</strong> ${escapeXml(line.slice(line.indexOf(': ') + 2))}</p>`).join('\n')}
+ <p><em>${escapeXml(guideSummary(ast))}</em></p>
${ast.guide.descriptionHtml ? `<div>${stepLinkRewrite(ast.guide.descriptionHtml, ast)}</div>` : ''}
+ ${tpl.toc && ast.steps.length > 1 ? '<ac:structured-macro ac:name="toc"></ac:structured-macro>' : ''}
${stepXml}
</body>
</html>
diff --git a/exporters/document-layout.js b/exporters/document-layout.js
new file mode 100644
index 0000000..1cec7f9
--- /dev/null
+++ b/exporters/document-layout.js
@@ -0,0 +1,40 @@
+'use strict';
+
+function anchorFor(stepOrNumber) {
+ const number = typeof stepOrNumber === 'string'
+ ? stepOrNumber
+ : stepOrNumber && stepOrNumber.number;
+ return `step-${String(number || '').replace(/\./g, '-')}`;
+}
+
+function tocEntries(ast, { maxDepth = Infinity } = {}) {
+ return (ast.steps || []).map((step) => ({
+ step,
+ anchor: anchorFor(step),
+ number: step.number,
+ title: step.title || 'Untitled step',
+ depth: Math.min(Number.isFinite(step.depth) ? step.depth : 0, maxDepth),
+ }));
+}
+
+function guideMetaLines(ast) {
+ const meta = ast?.guide?.metadata || {};
+ return [
+ meta.author && `Author: ${meta.author}`,
+ meta.coAuthors && `Co-authors: ${meta.coAuthors}`,
+ meta.organization && `Organization: ${meta.organization}`,
+ ].filter(Boolean);
+}
+
+function guideSummary(ast) {
+ const count = ast?.steps?.length || 0;
+ const generated = String(ast?.generatedAt || '').slice(0, 10);
+ return `${count} step${count === 1 ? '' : 's'} · generated ${generated}`;
+}
+
+module.exports = {
+ anchorFor,
+ tocEntries,
+ guideMetaLines,
+ guideSummary,
+};
diff --git a/exporters/docx.js b/exporters/docx.js
index d79bf6e..bf845ea 100644
--- a/exporters/docx.js
+++ b/exporters/docx.js
@@ -6,6 +6,7 @@ const { zipSync } = require('../core/zip');
const { escapeXml } = require('../core/util');
const { encodePng } = require('../core/png');
const { guideSlug, renderAllImages, LEVEL_LABEL, stepContentGroups, codeBlockText } = require('./common');
+const { guideMetaLines, guideSummary } = require('./document-layout');
/**
* DOCX exporter: WordprocessingML built directly (no dependency), one
@@ -15,6 +16,7 @@ const { guideSlug, renderAllImages, LEVEL_LABEL, stepContentGroups, codeBlockTex
const DEFAULT_TEMPLATE = {
includeImages: true,
+ includeToc: true,
imageWidthTwips: 9000, // ~15.9cm inside A4 margins
};
@@ -64,6 +66,36 @@ function drawing(relId, widthPx, heightPx, maxWidthTwips) {
`</pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r>`;
}
+function pageBreak() {
+ return p('<w:r><w:br w:type="page"/></w:r>');
+}
+
+function tocFieldParagraph() {
+ return p([
+ '<w:r><w:fldChar w:fldCharType="begin" w:dirty="true"/></w:r>',
+ '<w:r><w:instrText xml:space="preserve"> TOC \\o "1-3" \\h \\z \\u </w:instrText></w:r>',
+ '<w:r><w:fldChar w:fldCharType="separate"/></w:r>',
+ '<w:r><w:rPr><w:i/></w:rPr><w:t xml:space="preserve">Update contents in Word</w:t></w:r>',
+ '<w:r><w:fldChar w:fldCharType="end"/></w:r>',
+ ].join(''));
+}
+
+function headingStyleForDepth(depth) {
+ return `Heading${Math.min(3, depth + 1)}`;
+}
+
+function headingOutlineLevelForDepth(depth) {
+ return Math.min(2, Math.max(0, depth));
+}
+
+function headingParagraphProps(depth, forceNewPage = false) {
+ const parts = [];
+ if (forceNewPage) parts.push('<w:pageBreakBefore/>');
+ parts.push(`<w:pStyle w:val="${headingStyleForDepth(depth)}"/>`);
+ parts.push(`<w:outlineLvl w:val="${headingOutlineLevelForDepth(depth)}"/>`);
+ return parts.join('');
+}
+
function table(rows) {
const cols = Math.max(...rows.map((r) => r.length));
const grid = `<w:tblGrid>${'<w:gridCol w:w="2400"/>'.repeat(cols)}</w:tblGrid>`;
@@ -81,35 +113,121 @@ function table(rows) {
return `<w:tbl><w:tblPr><w:tblW w:w="0" w:type="auto"/>${borders}</w:tblPr>${grid}${body}</w:tbl>`;
}
+function stylesXml() {
+ const headingStyle = (styleId, name, outlineLvl, size, color) => `
+ <w:style w:type="paragraph" w:styleId="${styleId}">
+ <w:name w:val="${name}"/>
+ <w:basedOn w:val="Normal"/>
+ <w:next w:val="Normal"/>
+ <w:uiPriority w:val="${9 + outlineLvl}"/>
+ <w:qFormat/>
+ <w:unhideWhenUsed/>
+ <w:pPr>
+ <w:keepNext/>
+ <w:keepLines/>
+ <w:spacing w:before="${outlineLvl === 0 ? 360 : outlineLvl === 1 ? 240 : 180}" w:after="120"/>
+ <w:outlineLvl w:val="${outlineLvl}"/>
+ </w:pPr>
+ <w:rPr>
+ <w:b/>
+ <w:sz w:val="${size}"/>
+ <w:szCs w:val="${size}"/>
+ <w:color w:val="${color}"/>
+ </w:rPr>
+ </w:style>`;
+
+ return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+ <w:docDefaults>
+ <w:rPrDefault>
+ <w:rPr>
+ <w:sz w:val="22"/>
+ <w:szCs w:val="22"/>
+ <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
+ </w:rPr>
+ </w:rPrDefault>
+ <w:pPrDefault>
+ <w:pPr>
+ <w:spacing w:after="160"/>
+ </w:pPr>
+ </w:pPrDefault>
+ </w:docDefaults>
+ <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
+ <w:name w:val="Normal"/>
+ <w:qFormat/>
+ <w:uiPriority w:val="1"/>
+ <w:rPr>
+ <w:sz w:val="22"/>
+ <w:szCs w:val="22"/>
+ <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
+ </w:rPr>
+ </w:style>
+ ${headingStyle('Heading1', 'Heading 1', 0, 30, '2563EB')}
+ ${headingStyle('Heading2', 'Heading 2', 1, 26, '1D4ED8')}
+ ${headingStyle('Heading3', 'Heading 3', 2, 22, '1E40AF')}
+</w:styles>`;
+}
+
function exportDocx(ast, outDir, template = {}) {
const tpl = { ...DEFAULT_TEMPLATE, ...template };
const images = tpl.includeImages ? renderAllImages(ast) : new Map();
const media = []; // { name, data }
const rels = []; // relationship XML strings
- let relCounter = 0;
+ let relCounter = 1; // rId1 reserved for settings.xml; rId2 for styles.xml
+ let stepImageCount = 0;
+
+ rels.push(`<Relationship Id="rId${++relCounter}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>`);
const body = [];
- body.push(p(run(ast.guide.title, { bold: true, size: 48 })));
+ body.push(p(
+ run(ast.guide.title, { bold: true, size: 48 }),
+ '<w:pBdr><w:bottom w:val="single" w:sz="24" w:space="12" w:color="2563EB"/></w:pBdr>'
+ ));
if (ast.guide.descriptionText) body.push(p(run(ast.guide.descriptionText, { size: 22, color: '444444' })));
- body.push(p(run(`${ast.steps.length} steps — generated ${ast.generatedAt.slice(0, 10)}`, { size: 18, color: '888888' })));
+ for (const line of guideMetaLines(ast)) body.push(p(run(line, { size: 20, color: '6B7280' })));
+ body.push(p(run(guideSummary(ast), { size: 18, color: '888888' })));
+
+ body.push(pageBreak());
+
+ if (tpl.includeToc && ast.steps.length > 1) {
+ body.push(p(
+ run('Contents', { bold: true, size: 28 }),
+ '<w:pBdr><w:bottom w:val="single" w:sz="20" w:space="8" w:color="2563EB"/></w:pBdr>'
+ ));
+ body.push(tocFieldParagraph());
+ body.push(pageBreak());
+ }
+
+ const emitTextBlock = (tb) => {
+ const style = LEVEL_STYLE[tb.level] || LEVEL_STYLE.info;
+ const label = `${LEVEL_LABEL[tb.level] || 'Note'}${tb.title ? `: ${tb.title}` : ''}`;
+ body.push(p(
+ `${run(label, { bold: true, size: 20, color: style.color })}${tb.descriptionText ? run('\n' + tb.descriptionText, { size: 20, color: '1F2937' }) : ''}`,
+ `<w:shd w:val="clear" w:fill="${style.fill}"/><w:pBdr><w:left w:val="single" w:sz="24" w:space="4" w:color="${style.color}"/></w:pBdr>`
+ ));
+ };
for (const step of ast.steps) {
- const headSize = step.depth > 0 ? 26 : 30;
- body.push(p(run(`${step.number}. ${step.title || 'Untitled step'}`, { bold: true, size: headSize }),
- step.forceNewPage ? '<w:pageBreakBefore/>' : ''));
+ const headingLevel = Math.min(3, Math.max(1, step.depth + 1));
+ const headSize = headingLevel === 1 ? 30 : headingLevel === 2 ? 26 : 22;
+ body.push(p(
+ run(`${step.number}. ${step.title || 'Untitled step'}`, { bold: true, size: headSize }),
+ headingParagraphProps(step.depth, step.forceNewPage)
+ ));
const { before, rest } = stepContentGroups(step);
for (const tb of before) emitTextBlock(tb);
- if (step.descriptionText) body.push(p(run(step.descriptionText)));
+ if (step.descriptionText) body.push(p(run(step.descriptionText, { size: 20, color: '1F2937' })));
const img = images.get(step.stepId);
if (img) {
- relCounter += 1;
+ const relId = ++relCounter;
const name = `image${relCounter}.png`;
media.push({ name, data: encodePng(img) });
- rels.push(`<Relationship Id="rId${relCounter}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/${name}"/>`);
- body.push(p(drawing(relCounter, img.width, img.height, tpl.imageWidthTwips)));
+ rels.push(`<Relationship Id="rId${relId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/${name}"/>`);
+ body.push(p(drawing(relId, img.width, img.height, tpl.imageWidthTwips)));
+ stepImageCount += 1;
}
for (const block of rest) {
@@ -124,14 +242,10 @@ function exportDocx(ast, outDir, template = {}) {
}
}
- function emitTextBlock(tb) {
- const label = `${LEVEL_LABEL[tb.level] || 'Note'}${tb.title ? `: ${tb.title}` : ''}`;
- const style = LEVEL_STYLE[tb.level] || LEVEL_STYLE.info;
- body.push(p(
- run(label, { bold: true, size: 20, color: style.color }) + (tb.descriptionText ? run('\n' + tb.descriptionText, { size: 20 }) : ''),
- `<w:shd w:val="clear" w:fill="${style.fill}"/><w:pBdr><w:left w:val="single" w:sz="24" w:space="4" w:color="${style.color}"/></w:pBdr>`
- ));
- }
+ const settingsXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+ <w:updateFields w:val="true"/>
+</w:settings>`;
const documentXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
@@ -152,6 +266,8 @@ ${body.join('\n')}
<Default Extension="xml" ContentType="application/xml"/>
<Default Extension="png" ContentType="image/png"/>
<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
+<Override PartName="/word/settings.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml"/>
</Types>`,
},
{
@@ -166,16 +282,19 @@ ${body.join('\n')}
name: 'word/_rels/document.xml.rels',
data: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings" Target="settings.xml"/>
${rels.join('\n')}
</Relationships>`,
},
+ { name: 'word/settings.xml', data: settingsXml },
+ { name: 'word/styles.xml', data: stylesXml() },
...media.map((m) => ({ name: `word/media/${m.name}`, data: m.data, store: true })),
];
fs.mkdirSync(outDir, { recursive: true });
const file = path.join(outDir, `${guideSlug(ast)}.docx`);
fs.writeFileSync(file, zipSync(entries));
- return { file, imageCount: media.length };
+ return { file, imageCount: stepImageCount };
}
module.exports = { exportDocx, DEFAULT_TEMPLATE };
diff --git a/exporters/html.js b/exporters/html.js
index 852973e..d0aaeb0 100644
--- a/exporters/html.js
+++ b/exporters/html.js
@@ -5,6 +5,7 @@ const path = require('node:path');
const { escapeHtml } = require('../core/util');
const { encodePng } = require('../core/png');
const { guideSlug, renderAllImages, LEVEL_LABEL, stepContentGroups, codeBlockText } = require('./common');
+const { anchorFor, tocEntries, guideMetaLines, guideSummary } = require('./document-layout');
/**
* HTML exporters. Both variants are fully self-contained single files:
@@ -18,14 +19,11 @@ const { guideSlug, renderAllImages, LEVEL_LABEL, stepContentGroups, codeBlockTex
const DEFAULT_TEMPLATE = {
includeImages: true,
+ toc: true,
accentColor: '#2563eb',
customCss: '',
};
-function anchorFor(step) {
- return `step-${step.number.replace(/\./g, '-')}`;
-}
-
function dataUri(img) {
return `data:image/png;base64,${encodePng(img).toString('base64')}`;
}
@@ -42,6 +40,83 @@ function blockHtml(tb) {
return `<div class="block block-${tb.level}"><strong>${escapeHtml(LEVEL_LABEL[tb.level] || 'Note')}${tb.title ? `: ${escapeHtml(tb.title)}` : ''}</strong>${tb.descriptionHtml ? `<div>${tb.descriptionHtml}</div>` : ''}</div>`;
}
+function renderMetaChips(ast) {
+ return [
+ ...guideMetaLines(ast).map((line) => `<span class="chip">${escapeHtml(line)}</span>`),
+ `<span class="chip muted">${escapeHtml(guideSummary(ast))}</span>`,
+ ].join('');
+}
+
+function renderTocList(ast) {
+ return tocEntries(ast).map((entry) => `
+ <li class="d${entry.depth}">
+ <a href="#${entry.anchor}">
+ <span class="num">${escapeHtml(entry.number)}</span>
+ <span class="label">${escapeHtml(entry.title)}</span>
+ </a>
+ </li>
+ `).join('');
+}
+
+function renderCover(ast, tpl) {
+ return `
+ <section class="cover">
+ <div class="eyebrow">StepForge export</div>
+ <h1>${escapeHtml(ast.guide.title)}</h1>
+ <div class="rule" style="background:${tpl.accentColor}"></div>
+ ${ast.guide.descriptionHtml ? `<div class="desc">${stepLinkRewrite(ast.guide.descriptionHtml, ast)}</div>` : ''}
+ <div class="meta">${renderMetaChips(ast)}</div>
+ </section>`;
+}
+
+function renderStepCard(step, ast, images, tpl, { rich = false, selected = false } = {}) {
+ const title = `${escapeHtml(step.number)}. ${escapeHtml(step.title || 'Untitled step')}`;
+ const statusText = step.skipped
+ ? 'Skipped'
+ : step.status === 'in-progress'
+ ? 'In progress'
+ : step.status === 'done'
+ ? 'Done'
+ : 'Todo';
+ const head = rich ? `
+ <h2>
+ <label class="check"><input type="checkbox" class="step-done" data-step="${escapeHtml(step.stepId)}"></label>
+ <span class="step-num">${escapeHtml(step.number)}</span>
+ <span class="step-title">${escapeHtml(step.title || 'Untitled step')}</span>
+ <span class="status-chip status-${step.status || 'todo'}${step.skipped ? ' skipped' : ''}">${escapeHtml(statusText)}</span>
+ </h2>` : `<h2>${title}</h2>`;
+ return `
+ <section class="step-card${step.skipped ? ' skipped' : ''}${rich && selected ? ' selected' : ''}" id="${anchorFor(step)}">
+ ${head}
+ <div class="step-body">
+ ${stepBodyHtml(step, ast, images, tpl)}
+ </div>
+ </section>`;
+}
+
+function renderRichToc(ast) {
+ return tocEntries(ast).map((entry) => `
+ <li class="d${entry.depth}">
+ <a href="#${entry.anchor}">
+ <span class="num">${escapeHtml(entry.number)}</span>
+ <span class="label">${escapeHtml(entry.title)}</span>
+ </a>
+ </li>
+ `).join('');
+}
+
+function hexToRgb(hex) {
+ const m = /^#?([0-9a-f]{6})$/i.exec(String(hex || '').trim());
+ if (!m) return [37, 99, 235];
+ const n = Number.parseInt(m[1], 16);
+ return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+
+function bodyStyle(tpl) {
+ const [r, g, b] = hexToRgb(tpl.accentColor);
+ return `--accent:${tpl.accentColor};--accent-rgb:${r},${g},${b};`;
+}
+
function stepBodyHtml(step, ast, images, tpl) {
const parts = [];
const { before, rest } = stepContentGroups(step);
@@ -68,28 +143,346 @@ function stepBodyHtml(step, ast, images, tpl) {
}
const BASE_CSS = `
- body { font-family: system-ui, -apple-system, "Segoe UI", sans-serif; margin: 0 auto; max-width: 860px;
- padding: 24px; color: #1f2937; background: #ffffff; line-height: 1.55; }
- h1 { font-size: 1.7em; margin-bottom: .2em; }
- h2 { font-size: 1.2em; margin-top: 1.6em; border-bottom: 1px solid #e5e7eb; padding-bottom: .25em; }
- img.shot { max-width: 100%; height: auto; border: 1px solid #e5e7eb; border-radius: 6px; margin: .6em 0; }
- pre.code { background: #f3f4f6; padding: 12px; border-radius: 6px; overflow-x: auto; }
- table { border-collapse: collapse; margin: .6em 0; }
- th, td { border: 1px solid #d1d5db; padding: 4px 10px; text-align: left; }
- .block { border-left: 4px solid #3b82f6; background: #eff6ff; padding: 8px 12px; margin: .6em 0; border-radius: 0 6px 6px 0; }
- .block strong { color: #1d4ed8; }
+ :root {
+ --bg: #f4f7fb;
+ --bg-2: #eef3f9;
+ --panel: rgba(255, 255, 255, 0.92);
+ --panel-strong: #ffffff;
+ --panel-soft: #f8fbff;
+ --text: #152033;
+ --muted: #637084;
+ --border: rgba(119, 134, 156, 0.22);
+ --shadow: 0 18px 50px rgba(15, 23, 42, 0.08);
+ }
+ html { scroll-behavior: smooth; }
+ body {
+ margin: 0;
+ min-height: 100vh;
+ color: var(--text);
+ background:
+ radial-gradient(circle at top right, rgba(var(--accent-rgb), 0.16), transparent 26%),
+ radial-gradient(circle at bottom left, rgba(14, 165, 233, 0.11), transparent 22%),
+ linear-gradient(180deg, var(--bg), var(--bg-2));
+ line-height: 1.6;
+ font-family: "Aptos", "Segoe UI", "Helvetica Neue", Arial, sans-serif;
+ }
+ a { color: var(--accent); text-decoration: none; }
+ a:hover { text-decoration: underline; }
+ img.shot {
+ max-width: 100%;
+ height: auto;
+ border: 1px solid var(--border);
+ border-radius: 18px;
+ margin: 16px 0;
+ box-shadow: var(--shadow);
+ }
+ pre.code {
+ background: #0f172a;
+ color: #e2e8f0;
+ padding: 16px 18px;
+ border-radius: 18px;
+ overflow-x: auto;
+ box-shadow: var(--shadow);
+ }
+ pre.code code { font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace; }
+ table {
+ width: 100%;
+ border-collapse: collapse;
+ margin: 14px 0;
+ background: var(--panel-strong);
+ border: 1px solid var(--border);
+ border-radius: 16px;
+ overflow: hidden;
+ box-shadow: var(--shadow);
+ }
+ th, td {
+ border-bottom: 1px solid rgba(119, 134, 156, 0.16);
+ padding: 10px 12px;
+ text-align: left;
+ }
+ thead th {
+ background: var(--panel-soft);
+ color: var(--text);
+ font-size: .88rem;
+ letter-spacing: .02em;
+ text-transform: uppercase;
+ }
+ tbody tr:last-child td { border-bottom: 0; }
+ .doc { width: min(1120px, calc(100% - 32px)); margin: 0 auto; padding: 24px 0 40px; }
+ .cover, .toc-card, .step-card, .progress-card {
+ background: var(--panel);
+ border: 1px solid var(--border);
+ border-radius: 24px;
+ box-shadow: var(--shadow);
+ backdrop-filter: blur(10px);
+ }
+ .cover {
+ padding: 34px 36px 28px;
+ margin-bottom: 22px;
+ }
+ .cover .eyebrow {
+ color: var(--accent);
+ text-transform: uppercase;
+ letter-spacing: .16em;
+ font-size: .74rem;
+ font-weight: 800;
+ margin-bottom: 14px;
+ }
+ .cover h1 {
+ font-size: clamp(2rem, 4vw, 3.6rem);
+ line-height: 1.02;
+ margin: 0;
+ letter-spacing: -0.04em;
+ }
+ .cover .rule {
+ width: 132px;
+ height: 6px;
+ margin: 18px 0 16px;
+ border-radius: 999px;
+ box-shadow: 0 10px 24px rgba(var(--accent-rgb), 0.22);
+ }
+ .cover .desc {
+ max-width: 76ch;
+ color: var(--muted);
+ font-size: 1.02rem;
+ }
+ .cover .meta { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 18px; }
+ .chip {
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+ padding: 7px 11px;
+ border-radius: 999px;
+ background: rgba(var(--accent-rgb), 0.10);
+ color: var(--accent);
+ border: 1px solid rgba(var(--accent-rgb), 0.14);
+ font-size: .86rem;
+ font-weight: 650;
+ }
+ .chip.muted {
+ background: rgba(255, 255, 255, 0.55);
+ color: var(--muted);
+ border-color: rgba(119, 134, 156, 0.16);
+ }
+ .toc-card {
+ padding: 20px 22px;
+ margin-bottom: 24px;
+ }
+ .toc-card h2 {
+ margin: 0 0 16px;
+ font-size: 1.08rem;
+ letter-spacing: .02em;
+ }
+ .toc-list {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ }
+ .toc-list li { margin: 0; }
+ .toc-list a {
+ display: flex;
+ gap: 12px;
+ align-items: flex-start;
+ padding: 9px 12px;
+ border-radius: 14px;
+ color: inherit;
+ }
+ .toc-list a:hover {
+ background: rgba(var(--accent-rgb), 0.08);
+ text-decoration: none;
+ }
+ .toc-list .num {
+ min-width: 44px;
+ color: var(--accent);
+ font-weight: 800;
+ }
+ .toc-list .label { flex: 1; }
+ .toc-list li.d1 a { padding-left: 24px; }
+ .toc-list li.d2 a { padding-left: 44px; }
+ .toc-list li.d3 a { padding-left: 64px; }
+ .step-card {
+ margin: 20px 0;
+ padding: 22px 24px 18px;
+ border-left: 6px solid var(--accent);
+ }
+ .step-card h2 {
+ display: flex;
+ align-items: flex-start;
+ gap: 12px;
+ margin: 0 0 16px;
+ font-size: 1.28rem;
+ line-height: 1.15;
+ }
+ .step-card h2 .step-num {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ min-width: 2.1rem;
+ height: 2.1rem;
+ padding: 0 10px;
+ border-radius: 999px;
+ background: rgba(var(--accent-rgb), 0.11);
+ color: var(--accent);
+ font-size: .9rem;
+ font-weight: 800;
+ letter-spacing: .02em;
+ flex: none;
+ }
+ .step-card h2 .step-title { flex: 1; }
+ .status-chip {
+ display: inline-flex;
+ align-items: center;
+ height: 1.65rem;
+ padding: 0 9px;
+ border-radius: 999px;
+ font-size: .72rem;
+ letter-spacing: .08em;
+ text-transform: uppercase;
+ font-weight: 800;
+ color: #334155;
+ background: var(--panel-soft);
+ border: 1px solid rgba(119, 134, 156, 0.18);
+ }
+ .status-chip.status-done {
+ color: #047857;
+ background: #ecfdf5;
+ border-color: rgba(16, 185, 129, 0.22);
+ }
+ .status-chip.status-in-progress {
+ color: #b45309;
+ background: #fffbeb;
+ border-color: rgba(245, 158, 11, 0.22);
+ }
+ .status-chip.status-todo {
+ color: #475569;
+ }
+ .status-chip.skipped {
+ color: #92400e;
+ background: #fffbeb;
+ border-color: rgba(245, 158, 11, 0.24);
+ }
+ .step-card.skipped { opacity: .76; }
+ .step-body > .desc {
+ color: #243044;
+ }
+ .block {
+ position: relative;
+ border-left: 4px solid var(--accent);
+ background: rgba(var(--accent-rgb), 0.08);
+ padding: 14px 16px 14px 54px;
+ margin: 14px 0;
+ border-radius: 18px;
+ overflow: hidden;
+ }
+ .block::before {
+ content: 'i';
+ position: absolute;
+ left: 16px;
+ top: 14px;
+ width: 22px;
+ height: 22px;
+ border-radius: 999px;
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ background: rgba(var(--accent-rgb), 0.15);
+ color: var(--accent);
+ font-weight: 900;
+ font-size: 13px;
+ }
+ .block strong { color: var(--text); }
.block-warn { border-color: #f59e0b; background: #fffbeb; }
- .block-warn strong { color: #b45309; }
+ .block-warn::before { content: '!'; background: rgba(245, 158, 11, 0.16); color: #b45309; }
+ .block-warn strong { color: #92400e; }
.block-error { border-color: #ef4444; background: #fef2f2; }
+ .block-error::before { content: '!'; background: rgba(239, 68, 68, 0.14); color: #b91c1c; }
.block-error strong { color: #b91c1c; }
.block-success { border-color: #10b981; background: #ecfdf5; }
+ .block-success::before { content: '✓'; background: rgba(16, 185, 129, 0.14); color: #047857; }
.block-success strong { color: #047857; }
+ .footer-note {
+ margin-top: 20px;
+ color: var(--muted);
+ font-size: .84rem;
+ }
.skipped { opacity: .55; }
@media (prefers-color-scheme: dark) {
- body { background: #111827; color: #e5e7eb; }
- h2 { border-color: #374151; }
- pre.code, .block { background: #1f2937; }
- th, td { border-color: #4b5563; }
+ :root {
+ --bg: #0b1220;
+ --bg-2: #0f172a;
+ --panel: rgba(17, 24, 39, 0.9);
+ --panel-strong: #111827;
+ --panel-soft: #162033;
+ --text: #e5e7eb;
+ --muted: #98a2b3;
+ --border: rgba(148, 163, 184, 0.18);
+ --shadow: 0 16px 40px rgba(0, 0, 0, 0.25);
+ }
+ .status-chip { color: #d1d5db; }
+ .status-chip.skipped { color: #fbbf24; background: rgba(245, 158, 11, 0.12); }
+ .cover .desc, .step-body > .desc { color: #cbd5e1; }
+ .chip.muted { background: rgba(15, 23, 42, 0.75); color: #cbd5e1; }
+ .block { background: rgba(37, 99, 235, 0.12); }
+ .block-warn { background: rgba(245, 158, 11, 0.12); }
+ .block-error { background: rgba(239, 68, 68, 0.12); }
+ .block-success { background: rgba(16, 185, 129, 0.12); }
+ table { background: var(--panel-strong); }
+ th, td { border-bottom-color: rgba(148, 163, 184, 0.12); }
+ }
+`;
+
+const RICH_CSS = `
+ .layout-rich {
+ display: grid;
+ grid-template-columns: 300px minmax(0, 1fr);
+ gap: 24px;
+ align-items: start;
+ }
+ .toc-panel {
+ position: sticky;
+ top: 20px;
+ align-self: start;
+ }
+ .toc-card {
+ margin: 0;
+ max-height: calc(100vh - 40px);
+ overflow: auto;
+ }
+ .progress-card {
+ margin-bottom: 22px;
+ padding: 14px 18px;
+ }
+ .progress {
+ position: sticky;
+ top: 0;
+ z-index: 2;
+ background: transparent;
+ }
+ .progress .label {
+ font-size: .86rem;
+ font-weight: 700;
+ color: var(--muted);
+ margin-bottom: 8px;
+ }
+ .progress .bar {
+ height: 8px;
+ background: rgba(148, 163, 184, 0.18);
+ border-radius: 999px;
+ overflow: hidden;
+ }
+ .progress .fill {
+ height: 100%;
+ width: 0;
+ background: var(--accent);
+ transition: width .2s ease;
+ }
+ label.check { margin-right: 0; }
+ label.check input { transform: translateY(1px); }
+ .step-card h2 .step-title { min-width: 0; }
+ @media (max-width: 960px) {
+ .layout-rich { grid-template-columns: 1fr; }
+ .toc-panel { position: static; }
+ .toc-card { max-height: none; }
}
`;
@@ -97,12 +490,16 @@ function exportHtmlSimple(ast, outDir, template = {}) {
const tpl = { ...DEFAULT_TEMPLATE, ...template };
fs.mkdirSync(outDir, { recursive: true });
const images = tpl.includeImages ? renderAllImages(ast) : new Map();
-
- const stepsHtml = ast.steps.map((step) => `
-<section class="step${step.skipped ? ' skipped' : ''}" id="${anchorFor(step)}">
- <h2>${escapeHtml(step.number)}. ${escapeHtml(step.title || 'Untitled step')}</h2>
- ${stepBodyHtml(step, ast, images, tpl)}
-</section>`).join('\n');
+ const toc = tpl.toc && ast.steps.length > 1
+ ? `
+ <section class="toc-card">
+ <h2>Contents</h2>
+ <ul class="toc-list">
+ ${renderTocList(ast)}
+ </ul>
+ </section>`
+ : '';
+ const stepsHtml = ast.steps.map((step) => renderStepCard(step, ast, images, tpl)).join('\n');
const html = `<!DOCTYPE html>
<html lang="en">
@@ -112,11 +509,13 @@ function exportHtmlSimple(ast, outDir, template = {}) {
<title>${escapeHtml(ast.guide.title)}
-
-${escapeHtml(ast.guide.title)}
-${ast.guide.descriptionHtml ? `${ast.guide.descriptionHtml}
` : ''}
+
+
+${renderCover(ast, tpl)}
+${toc}
${stepsHtml}
-
+
+
`;
@@ -130,39 +529,19 @@ function exportHtmlRich(ast, outDir, template = {}) {
fs.mkdirSync(outDir, { recursive: true });
const images = tpl.includeImages ? renderAllImages(ast) : new Map();
const storageKey = `stepforge-progress-${ast.guide.id}`;
+ const tocHtml = tpl.toc && ast.steps.length > 1
+ ? `
+ `
+ : '';
- const tocHtml = ast.steps.map((step) =>
- `${escapeHtml(step.number)}. ${escapeHtml(step.title || 'Untitled step')}`
- ).join('\n');
-
- const stepsHtml = ast.steps.map((step) => `
-`).join('\n');
-
- const richCss = `
- .layout { display: flex; gap: 28px; max-width: 1180px; margin: 0 auto; }
- nav.toc { position: sticky; top: 16px; align-self: flex-start; min-width: 220px; max-width: 280px;
- max-height: calc(100vh - 32px); overflow-y: auto; font-size: .92em;
- border: 1px solid #e5e7eb; border-radius: 8px; padding: 14px; }
- nav.toc ul { list-style: none; margin: 0; padding: 0; }
- nav.toc li { margin: .25em 0; }
- nav.toc li.d1 { padding-left: 14px; } nav.toc li.d2 { padding-left: 28px; }
- nav.toc a { color: inherit; text-decoration: none; }
- nav.toc a:hover { color: ${tpl.accentColor}; }
- main { flex: 1; min-width: 0; }
- .progress { position: sticky; top: 0; background: inherit; padding: 8px 0; z-index: 2; }
- .progress .bar { height: 6px; background: #e5e7eb; border-radius: 3px; overflow: hidden; }
- .progress .fill { height: 100%; width: 0; background: ${tpl.accentColor}; transition: width .2s; }
- label.check { margin-right: 8px; }
- section.step.done h2 { text-decoration: line-through; opacity: .6; }
- @media (max-width: 900px) { .layout { flex-direction: column; } nav.toc { position: static; max-width: none; } }
- @media (prefers-color-scheme: dark) { nav.toc { border-color: #374151; } .progress .bar { background: #374151; } }
-`;
+ const stepsHtml = ast.steps.map((step) => renderStepCard(step, ast, images, tpl, { rich: true })).join('\n');
const script = `
(function () {
@@ -199,19 +578,19 @@ function exportHtmlRich(ast, outDir, template = {}) {
${escapeHtml(ast.guide.title)}
-
+
-
-