@entropicwarrior/sdoc 0.1.11 → 0.1.13

package/README.md

@@ -20,6 +20,8 @@ A plain-text documentation format designed for AI-agent efficiency. Explicit bra
 
 **A document site builder** — serve a folder of SDOC files as a browsable site with sidebar navigation, search, and split-pane comparison.
 
+**PDF and HTML export** — export any document to A4 PDF via headless Chrome, or to standalone HTML. Available as both a CLI tool and a VS Code command.
+
 **A VS Code extension** — live preview, sticky scroll, code folding, document symbols, mermaid rendering, and commands for all the above.
 
 ## Quick Start
@@ -41,6 +43,15 @@ node tools/build-slides.js deck.sdoc -o slides.html
 
 Each top-level scope becomes a slide. Set `type: slides` in `@meta`. See `lexica/slide-authoring.sdoc` for the full authoring guide.
 
+### Export to PDF or HTML
+
+```bash
+node tools/build-doc.js doc.sdoc                   # PDF (requires Chrome)
+node tools/build-doc.js doc.sdoc --html -o doc.html # HTML
+```
+
+Or use **SDOC: Export PDF** / **SDOC: Export HTML** from the VS Code Command Palette.
+
 ### Browse documents
 
 ```bash
@@ -91,7 +102,8 @@ Annotate text with semantic meaning that renders as colored highlights:
 |---|---|---|
 | `{+text+}` | Positive | Green |
 | `{=text=}` | Neutral | Blue |
-| `{^text^}` | Caution | Amber |
+| `{^text^}` | Note | Amber |
+| `{?text?}` | Caution | Dark amber |
 | `{!text!}` | Warning | Orange |
 | `{-text-}` | Negative | Red |
 | `{~text~}` | Highlight | Yellow |

package/lexica/sdoc-authoring.sdoc

@@ -181,7 +181,8 @@
                 \`\$\$E = mc^2\$\$\` | Display math (centered)
                 \`\{+text+\}\` | Positive marker (green)
                 \`\{=text=\}\` | Neutral marker (blue)
-                \`\{^text^\}\` | Caution marker (amber)
+                \`\{^text^\}\` | Note marker (amber)
+                \`\{?text?\}\` | Caution marker (dark amber)
                 \`\{!text!\}\` | Warning marker (orange)
                 \`\{-text-\}\` | Negative marker (red)
                 \`\{~text~\}\` | Highlight (yellow)

package/lexica/specification.sdoc

@@ -454,7 +454,8 @@ Content of Section B.
                 - Display math: `$$E = mc^2$$` (centered block)
                 - Positive marker: `{+text+}` (green highlight)
                 - Neutral marker: `{=text=}` (blue highlight)
-                - Caution marker: `{^text^}` (amber highlight)
+                - Note marker: `{^text^}` (amber highlight)
+                - Caution marker: `{?text?}` (dark amber highlight)
                 - Warning marker: `{!text!}` (orange highlight)
                 - Negative marker: `{-text-}` (red highlight)
                 - Highlight: `{~text~}` (yellow highlight)
@@ -606,6 +607,20 @@ Content of Section B.
     {
         The VSCode extension provides an interactive preview with the following features. These are preview-only behaviours and do not affect the SDOC format or static HTML export.
 
+        # Theme Support @theme-support
+        {
+            The preview automatically follows the user's VSCode colour theme. Light, dark, and high-contrast themes are all supported.
+
+            {[.]
+                - Theme detection is CSS-driven: VSCode adds \`vscode-dark\`, \`vscode-light\`, \`vscode-high-contrast\`, or \`vscode-high-contrast-light\` classes to the webview body element
+                - Dark mode overrides the \`--sdoc-*\` CSS custom properties and hardcoded \`rgba()\` colours (table headers, code blocks, confidential notices, error blocks)
+                - Mermaid diagrams use the \`dark\` theme when in a dark colour theme and \`neutral\` otherwise
+                - Theme changes take effect immediately (CSS-driven) and trigger a full preview rebuild (for Mermaid re-initialisation)
+                - Exported HTML follows the user's OS colour preference via \`@media (prefers-color-scheme: dark)\`. Print output always uses light theme colours
+                - Custom stylesheets (\`sdoc.config.json\` or \`@meta style\`) that use \`--sdoc-*\` variables inherit dark values automatically. Hardcoded colours in custom styles are not overridden
+            }
+        }
+
         # Collapsible Scopes @collapsible-scopes
         {
             Scope headings that have children display a toggle triangle, visible on hover. Clicking the triangle collapses the scope's children (hides the content below the heading). Clicking again expands them.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {
@@ -42,6 +42,7 @@
     "onCommand:sdoc.preview",
     "onCommand:sdoc.previewToSide",
     "onCommand:sdoc.exportHtml",
+    "onCommand:sdoc.exportPdf",
     "onCommand:sdoc.openInBrowser",
     "onCommand:sdoc.browseDocs",
     "onCommand:sdoc.newKnowledgeFile",
@@ -87,6 +88,11 @@
         "title": "SDOC: Export HTML",
         "icon": "$(desktop-download)"
       },
+      {
+        "command": "sdoc.exportPdf",
+        "title": "SDOC: Export PDF",
+        "icon": "$(file-pdf)"
+      },
       {
         "command": "sdoc.openInBrowser",
         "title": "SDOC: Open in Browser",
@@ -128,6 +134,12 @@
               "foreground": "#b08a1a"
             }
           },
+          {
+            "scope": "markup.keyword.caution.sdoc",
+            "settings": {
+              "foreground": "#c06a00"
+            }
+          },
           {
             "scope": "markup.keyword.warning.sdoc",
             "settings": {
@@ -171,12 +183,17 @@
         },
         {
           "command": "sdoc.exportHtml",
-          "when": "activeWebviewPanelId == 'sdoc.preview'",
+          "when": "activeWebviewPanelId == 'sdoc.preview' || editorLangId == sdoc",
+          "group": "navigation"
+        },
+        {
+          "command": "sdoc.exportPdf",
+          "when": "activeWebviewPanelId == 'sdoc.preview' || editorLangId == sdoc",
           "group": "navigation"
         },
         {
           "command": "sdoc.openInBrowser",
-          "when": "activeWebviewPanelId == 'sdoc.preview'",
+          "when": "activeWebviewPanelId == 'sdoc.preview' || editorLangId == sdoc",
           "group": "navigation"
         }
       ],

package/src/notion-renderer.js

@@ -139,6 +139,7 @@ function flattenInlineNodes(nodes, annotations, href) {
         break;
       case "mark_positive":
       case "mark_neutral":
+      case "mark_note":
       case "mark_caution":
       case "mark_warning":
       case "mark_negative":

package/src/sdoc.js

@@ -8,7 +8,7 @@ const COMMAND_LIST_NUMBER = "{[#]";
 const COMMAND_TABLE = "{[table]";
 const COMMAND_CODE_FENCE = "```";
 
-const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">", "$", "+", "=", "-", "^"]);
+const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">", "$", "+", "=", "-", "^", "?"]);
 
 let _katex = null;
 let _katexLoaded = false;
@@ -1205,7 +1205,8 @@ function parseInline(text) {
       let mt = null;
       if (mc === "+") mt = "mark_positive";
       else if (mc === "=") mt = "mark_neutral";
-      else if (mc === "^") mt = "mark_caution";
+      else if (mc === "^") mt = "mark_note";
+      else if (mc === "?") mt = "mark_caution";
       else if (mc === "!") mt = "mark_warning";
       else if (mc === "-") mt = "mark_negative";
       else if (mc === "~") mt = "mark_highlight";
@@ -1366,6 +1367,8 @@ function renderInlineNodes(nodes) {
           return `<span class="sdoc-mark sdoc-mark-positive">${renderInlineNodes(node.children)}</span>`;
         case "mark_neutral":
           return `<span class="sdoc-mark sdoc-mark-neutral">${renderInlineNodes(node.children)}</span>`;
+        case "mark_note":
+          return `<span class="sdoc-mark sdoc-mark-note">${renderInlineNodes(node.children)}</span>`;
         case "mark_caution":
           return `<span class="sdoc-mark sdoc-mark-caution">${renderInlineNodes(node.children)}</span>`;
         case "mark_warning":
@@ -1929,11 +1932,12 @@ const DEFAULT_STYLE = `
     padding: 0.05em 0.3em;
     font-weight: 500;
   }
-  .sdoc-mark-positive { background-color: rgba(34, 139, 34, 0.15); color: #166016; }
-  .sdoc-mark-neutral  { background-color: rgba(59, 130, 195, 0.15); color: #245d8a; }
-  .sdoc-mark-caution  { background-color: rgba(200, 150, 30, 0.18); color: #7a5f0e; }
-  .sdoc-mark-warning  { background-color: rgba(255, 120, 0, 0.18); color: #b35400; }
-  .sdoc-mark-negative { background-color: rgba(187, 50, 50, 0.15); color: #911e1e; }
+  .sdoc-mark-positive  { background-color: rgba(34, 139, 34, 0.15); color: #166016; }
+  .sdoc-mark-neutral   { background-color: rgba(59, 130, 195, 0.15); color: #245d8a; }
+  .sdoc-mark-note      { background-color: rgba(190, 170, 0, 0.15); color: #6b5d00; }
+  .sdoc-mark-caution   { background-color: rgba(217, 130, 10, 0.18); color: #8a5000; }
+  .sdoc-mark-warning   { background-color: rgba(245, 115, 0, 0.20); color: #c05600; }
+  .sdoc-mark-negative  { background-color: rgba(210, 25, 25, 0.18); color: #a81414; }
   .sdoc-mark-highlight { background-color: rgba(255, 255, 0, 0.75); }
 
   .sdoc-image {
@@ -2081,8 +2085,12 @@ function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
   const cssBase = options.cssOverride ?? DEFAULT_STYLE;
   const cssAppend = options.cssAppend ? `\n${options.cssAppend}\n${PRINT_STYLE}` : `\n${PRINT_STYLE}`;
   const scriptTag = options.script ? `\n<script>${options.script}</script>` : "";
+  const mermaidTheme = options.mermaidTheme ?? "neutral";
+  const mermaidInit = mermaidTheme === "auto"
+    ? `var isDark=window.matchMedia("(prefers-color-scheme:dark)").matches;mermaid.initialize({startOnLoad:true,theme:isDark?"dark":"neutral",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});`
+    : `mermaid.initialize({startOnLoad:true,theme:"${mermaidTheme}",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});`;
   const mermaidScript = hasMermaidBlocks(parsed.nodes)
-    ? `\n<script src="${MERMAID_CDN}"></script>\n<script>mermaid.initialize({startOnLoad:true,theme:"neutral",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});</script>`
+    ? `\n<script src="${MERMAID_CDN}"></script>\n<script>${mermaidInit}</script>`
     : "";
   const katexCssTag = body.includes('class="katex"')
     ? `\n<link rel="stylesheet" href="${KATEX_CDN_CSS}" />`

package/src/slide-pdf.js

@@ -1,4 +1,4 @@
-// SDOC Slides — PDF export via headless Chrome.
+// SDOC — PDF export via headless Chrome.
 // Zero dependencies: uses child_process to shell out to the system Chrome/Chromium.
 
 const { execFile } = require("child_process");
@@ -51,7 +51,11 @@ function findChrome() {
   return null;
 }
 
-function exportPdf(htmlPath, pdfPath) {
+// Generic PDF export. Options:
+//   paperWidth  — inches (default 8.27 = A4)
+//   paperHeight — inches (default 11.69 = A4)
+//   noHeaderFooter — suppress Chrome header/footer (default true)
+function chromePdf(htmlPath, pdfPath, options = {}) {
   return new Promise((resolve, reject) => {
     const chrome = findChrome();
     if (!chrome) {
@@ -69,20 +73,26 @@ function exportPdf(htmlPath, pdfPath) {
     // the browser process by default, which corrupts PDF output).
     const tmpProfile = fs.mkdtempSync(path.join(os.tmpdir(), "sdoc-chrome-"));
 
-    // 13.333 x 7.5 inches = 16:9 landscape (standard presentation aspect ratio)
+    const paperWidth = options.paperWidth ?? 8.27;
+    const paperHeight = options.paperHeight ?? 11.69;
+
     const args = [
       "--headless=new",
       "--disable-gpu",
       "--no-first-run",
       "--no-default-browser-check",
       "--user-data-dir=" + tmpProfile,
-      "--no-pdf-header-footer",
       "--print-to-pdf=" + resolvedPdf,
-      "--print-to-pdf-paper-width=13.333",
-      "--print-to-pdf-paper-height=7.5",
-      fileUrl,
+      "--print-to-pdf-paper-width=" + paperWidth,
+      "--print-to-pdf-paper-height=" + paperHeight,
     ];
 
+    if (options.noHeaderFooter !== false) {
+      args.push("--no-pdf-header-footer");
+    }
+
+    args.push(fileUrl);
+
     execFile(chrome, args, { timeout: 30000 }, (err, _stdout, stderr) => {
       // Clean up temp profile
       fs.rm(tmpProfile, { recursive: true, force: true }, () => {});
@@ -96,4 +106,14 @@ function exportPdf(htmlPath, pdfPath) {
   });
 }
 
-module.exports = { findChrome, exportPdf };
+// Slide PDF: 16:9 landscape (13.333 x 7.5 inches)
+function exportSlidePdf(htmlPath, pdfPath) {
+  return chromePdf(htmlPath, pdfPath, { paperWidth: 13.333, paperHeight: 7.5 });
+}
+
+// Document PDF: A4 portrait (8.27 x 11.69 inches)
+function exportDocPdf(htmlPath, pdfPath) {
+  return chromePdf(htmlPath, pdfPath);
+}
+
+module.exports = { findChrome, exportSlidePdf, exportDocPdf, chromePdf };

package/src/slide-renderer.js

@@ -243,7 +243,8 @@ function renderSlides(nodes, options = {}) {
   const {
     meta = {},
     themeCss = "",
-    themeJs = ""
+    themeJs = "",
+    darkMode = false
   } = options;
 
   // The nodes from extractMeta have @meta already stripped.
@@ -325,11 +326,29 @@ function renderSlides(nodes, options = {}) {
   .notes { display: none; }
 }`;
 
-  const cssTag = `<style>\n${structuralCss}\n${themeCss}\n</style>`;
+  const darkCss = darkMode ? `
+/* Dark mode overrides */
+body { background: #1e1e1e; color: #d4d4d4; }
+h1, h2 { color: #e0e0e0; }
+h3 { color: #b0b0b0; }
+p, li { color: #b0b0b0; }
+th { color: #9d9d9d; }
+th, td { border-bottom-color: rgba(255, 255, 255, 0.1); }
+pre { background: rgba(255, 255, 255, 0.06); border-color: rgba(255, 255, 255, 0.1); }
+p code, li code { background: rgba(255, 255, 255, 0.08); }
+blockquote { border-left-color: #5b9bd5; color: #9d9d9d; }
+blockquote p { color: #9d9d9d; }
+.nav-prev, .nav-next { color: rgba(255, 255, 255, 0.7); }
+.sdoc-company-footer { color: rgba(255, 255, 255, 0.35); }
+.sdoc-confidential-notice { color: rgba(235, 120, 120, 0.7); }
+` : "";
+
+  const cssTag = `<style>\n${structuralCss}\n${themeCss}\n${darkCss}</style>`;
   const jsTag = themeJs ? `<script>\n${themeJs}\n</script>` : "";
   const mermaidCdn = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js";
+  const mermaidTheme = darkMode ? "dark" : "neutral";
   const mermaidTag = slidesHtml.includes('class="mermaid"')
-    ? `\n<script src="${mermaidCdn}"></script>\n<script>mermaid.initialize({startOnLoad:true,theme:"neutral",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});</script>`
+    ? `\n<script src="${mermaidCdn}"></script>\n<script>mermaid.initialize({startOnLoad:true,theme:"${mermaidTheme}",themeCSS:".node rect, .node polygon, .node circle { rx: 4; ry: 4; }"});</script>`
     : "";
   const katexCssCdn = "https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css";
   const katexTag = slidesHtml.includes('class="katex"')

package/tools/build-doc.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// SDOC Document — CLI tool for HTML and PDF export
+//
+// Usage:
+//   node tools/build-doc.js input.sdoc [-o output] [--html]
+//
+// Default output is PDF (requires Chrome/Chromium).
+// Use --html for HTML-only output (no Chrome needed).
+// If -o is omitted, writes to input.pdf (or input.html with --html).
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { parseSdoc, extractMeta, resolveIncludes, renderHtmlDocumentFromParsed } = require("../src/sdoc");
+
+const CONFIG_FILENAME = "sdoc.config.json";
+
+function usage() {
+  console.error("Usage: build-doc <input.sdoc> [-o output] [--html]");
+  process.exit(1);
+}
+
+function readJson(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function loadCss(filePath) {
+  if (!filePath) return null;
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function resolvePath(baseDir, target) {
+  if (!target) return "";
+  if (path.isAbsolute(target)) return target;
+  return path.join(baseDir, target);
+}
+
+function mergeConfig(target, config, baseDir) {
+  if (!config || typeof config !== "object") return;
+  if (typeof config.style === "string") {
+    target.style = resolvePath(baseDir, config.style);
+  }
+  if (config.styleAppend) {
+    const list = Array.isArray(config.styleAppend) ? config.styleAppend : [config.styleAppend];
+    for (const item of list) {
+      if (typeof item === "string") {
+        target.styleAppend.push(resolvePath(baseDir, item));
+      }
+    }
+  }
+  if (typeof config.header === "string") target.header = config.header;
+  if (typeof config.footer === "string") target.footer = config.footer;
+}
+
+function loadConfigForFile(filePath) {
+  const startDir = path.dirname(path.resolve(filePath));
+  const root = path.parse(startDir).root;
+  const chain = [];
+  let current = startDir;
+
+  while (current) {
+    const configPath = path.join(current, CONFIG_FILENAME);
+    if (fs.existsSync(configPath)) {
+      const parsed = readJson(configPath);
+      if (parsed) chain.push({ dir: current, config: parsed });
+    }
+    if (current === root) break;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  const merged = { style: null, styleAppend: [], header: "", footer: "" };
+  for (const entry of chain.reverse()) {
+    mergeConfig(merged, entry.config, entry.dir);
+  }
+  return merged;
+}
+
+function resolveMetaStyles(meta, documentPath) {
+  const docDir = documentPath ? path.dirname(documentPath) : "";
+  const result = { styleCss: null, styleAppendCss: null };
+  if (meta && meta.stylePath) {
+    result.styleCss = loadCss(resolvePath(docDir, meta.stylePath));
+  }
+  if (meta && meta.styleAppendPath) {
+    result.styleAppendCss = loadCss(resolvePath(docDir, meta.styleAppendPath));
+  }
+  return result;
+}
+
+async function buildHtml(filePath) {
+  const resolvedPath = path.resolve(filePath);
+  const text = fs.readFileSync(resolvedPath, "utf8");
+  const parsed = parseSdoc(text);
+
+  if (parsed.errors.length > 0) {
+    for (const error of parsed.errors) {
+      console.error(`Warning: line ${error.line}: ${error.message}`);
+    }
+  }
+
+  const metaResult = extractMeta(parsed.nodes);
+  const config = loadConfigForFile(resolvedPath);
+  const metaStyles = resolveMetaStyles(metaResult.meta, resolvedPath);
+
+  const docDir = path.dirname(resolvedPath);
+  await resolveIncludes(metaResult.nodes, (src) => {
+    const resolved = resolvePath(docDir, src);
+    return fs.readFileSync(resolved, "utf8");
+  });
+
+  const cssOverride = metaStyles.styleCss ?? loadCss(config.style);
+  const cssAppendParts = [];
+  if (config.styleAppend && config.styleAppend.length) {
+    for (const stylePath of config.styleAppend) {
+      const css = loadCss(stylePath);
+      if (css) cssAppendParts.push(css);
+    }
+  }
+  if (metaStyles.styleAppendCss) {
+    cssAppendParts.push(metaStyles.styleAppendCss);
+  }
+
+  const title = path.basename(resolvedPath, ".sdoc");
+
+  return renderHtmlDocumentFromParsed(
+    { nodes: metaResult.nodes, errors: parsed.errors },
+    title,
+    {
+      meta: metaResult.meta,
+      config,
+      cssOverride: cssOverride || undefined,
+      cssAppend: cssAppendParts.join("\n") || undefined,
+    }
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let inputPath = null;
+  let outputPath = null;
+  let htmlMode = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "-o" && i + 1 < args.length) {
+      outputPath = args[++i];
+    } else if (args[i] === "--html") {
+      htmlMode = true;
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      usage();
+    } else if (!inputPath) {
+      inputPath = args[i];
+    } else {
+      console.error(`Unknown argument: ${args[i]}`);
+      usage();
+    }
+  }
+
+  if (!inputPath) usage();
+
+  const resolvedInput = path.resolve(inputPath);
+  if (!fs.existsSync(resolvedInput)) {
+    console.error(`File not found: ${resolvedInput}`);
+    process.exit(1);
+  }
+
+  const html = await buildHtml(resolvedInput);
+
+  if (htmlMode) {
+    if (!outputPath) {
+      outputPath = resolvedInput.replace(/\.sdoc$/i, "") + ".html";
+    }
+    const resolvedOutput = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+    fs.writeFileSync(resolvedOutput, html, "utf-8");
+    console.log(`HTML: ${resolvedOutput}`);
+  } else {
+    const { exportDocPdf } = require("../src/slide-pdf");
+
+    if (!outputPath) {
+      outputPath = resolvedInput.replace(/\.sdoc$/i, "") + ".pdf";
+    }
+    const resolvedOutput = path.resolve(outputPath);
+
+    // Write HTML to temp file for Chrome
+    const tmpHtml = path.join(os.tmpdir(), "sdoc-doc-" + Date.now() + ".html");
+    fs.writeFileSync(tmpHtml, html, "utf-8");
+
+    try {
+      await exportDocPdf(tmpHtml, resolvedOutput);
+      console.log(`PDF: ${resolvedOutput}`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    } finally {
+      try { fs.unlinkSync(tmpHtml); } catch {}
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});