@zvndev/darkmown 1.2.1 → 1.4.0

package/src/highlight.js

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// Build-time syntax highlighting: the markdown-it `highlight` callback (wired
+// onto both markdown-it instances in `src/compiler/markdown.js`) plus the
+// framework stylesheet that maps highlight.js token classes onto `$code-*` skin
+// tokens. Highlighting is HTML + CSS only — no runtime, no client JS. The
+// stylesheet is emitted (and linked) ONLY on pages that contain a highlighted
+// code block, mirroring the pay-for-what-you-use behavior modules.
+//
+// Closed-whitelist philosophy: the highlighter is highlight.js and is NOT
+// configurable. A fenced block whose language is unknown or absent is left for
+// markdown-it to render as plain escaped `<code>` (graceful degradation); inline
+// `` `code` `` is never highlighted.
+// ---------------------------------------------------------------------------
+
+import hljs from "highlight.js";
+
+// Stamped onto highlighted output so the compiler can detect (in the rendered
+// HTML) that a block was highlighted and flag `assets.hasCode` for this page —
+// the markdown-it `highlight` callback has no access to the compilation object.
+// Guarantees a marker even for a token-less snippet that produced no `hljs-*`
+// spans, so detection never misses.
+export const HLJS_MARKER = "hljs";
+
+/**
+ * markdown-it `highlight` callback. Returns highlight.js's escaped token HTML for
+ * a known language (wrapped so the `hljs` marker is always present), or `""` to
+ * defer to markdown-it's own escaping for an unknown/absent language — the
+ * graceful-degradation path that renders a plain `<code>` with no highlighting.
+ *
+ * markdown-it does NOT escape a non-empty return value (it is trusted HTML), so
+ * we must return already-escaped content — `hljs.highlight` escapes its output.
+ * @param {string} code The fenced block's raw source.
+ * @param {string} lang The info string (language) after the opening fence, if any.
+ * @returns {string} Highlighted, escaped HTML, or `""` to defer to markdown-it.
+ */
+export function highlightCode(code, lang) {
+  // No language, or a language highlight.js doesn't know → plain escaped code.
+  if (!lang || !hljs.getLanguage(lang)) return "";
+  // `ignoreIllegals` keeps a snippet that doesn't fully parse from throwing — it
+  // still highlights best-effort instead of degrading the whole build.
+  const { value } = hljs.highlight(code, { language: lang, ignoreIllegals: true });
+  return `<span class="${HLJS_MARKER}">${value}</span>`;
+}
+
+/**
+ * Detect whether a rendered HTML fragment contains a highlighted code block, so
+ * the page-level `assets.hasCode` flag (and thus the highlight stylesheet) is set
+ * only when highlighting actually happened. Matches the `hljs` marker stamped by
+ * {@link highlightCode}; a page with only plain/unknown-language code never trips it.
+ * @param {string} html Rendered body HTML.
+ * @returns {boolean}
+ */
+export function htmlHasHighlight(html) {
+  return html.includes(`class="${HLJS_MARKER}"`);
+}
+
+// The framework highlight stylesheet. Maps highlight.js token classes onto
+// `$code-*` skin tokens via CSS custom properties, so code blocks dark-mode for
+// free through the existing `tokens dark` / `:theme` system with ZERO JS — the
+// same `--code-*` variables flip under the OS dark preference or a manual theme
+// toggle. The `var(..., fallback)` second argument keeps highlighting legible
+// even on a project whose skin omits the `$code-*` tokens entirely.
+//
+// Emitted to `/__wd/highlight.css` and linked only on pages that use it.
+export const HIGHLIGHT_CSS = `/* Darkmown syntax highlighting — highlight.js classes mapped to $code-* skin
+   tokens. Dark mode is automatic: the tokens swap under tokens dark / :theme,
+   so this stylesheet ships zero JavaScript. */
+.hljs {
+  color: var(--code-fg, #e9efe7);
+  background: var(--code-bg, #1b2420);
+}
+.hljs-comment,
+.hljs-quote {
+  color: var(--code-comment, #7d8a82);
+  font-style: italic;
+}
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-literal,
+.hljs-section,
+.hljs-doctag,
+.hljs-name {
+  color: var(--code-keyword, #d39bda);
+}
+.hljs-string,
+.hljs-regexp,
+.hljs-meta .hljs-string,
+.hljs-attr,
+.hljs-selector-attr,
+.hljs-selector-pseudo,
+.hljs-addition {
+  color: var(--code-string, #8fd28a);
+}
+.hljs-title,
+.hljs-title.function_,
+.hljs-built_in,
+.hljs-class .hljs-title,
+.hljs-selector-class,
+.hljs-selector-id {
+  color: var(--code-function, #82c0e9);
+}
+.hljs-number,
+.hljs-symbol,
+.hljs-bullet,
+.hljs-link,
+.hljs-meta {
+  color: var(--code-number, #e3a76f);
+}
+.hljs-variable,
+.hljs-template-variable,
+.hljs-type,
+.hljs-attribute,
+.hljs-params,
+.hljs-tag,
+.hljs-deletion,
+.hljs-punctuation,
+.hljs-operator {
+  color: var(--code-punctuation, #b9c4be);
+}
+.hljs-emphasis {
+  font-style: italic;
+}
+.hljs-strong {
+  font-weight: 600;
+}
+`;

package/src/router.js

@@ -1,20 +1,38 @@
 import fs from "node:fs";
 import path from "node:path";
+import { parseFrontmatter } from "./compiler.js";
 import { isHiddenName, pageExtensions } from "./config.js";
 
 /**
- * A discovered page route: the source file and its public route path.
+ * @typedef {import("./compiler.js").Meta} Meta
+ */
+
+/**
+ * A discovered page route: the source file, its public route path, and its
+ * parsed frontmatter. `meta` is read ONCE here — the single source of truth for
+ * "is this a draft" and for the downstream sitemap/RSS feeds (which never see a
+ * draft, since drafts are filtered out below).
  * @typedef {object} Route
  * @property {string} file Absolute path to the source `.md`/`.wd` file.
  * @property {string} route Public route path (always trailing-slashed, e.g. `/about/`).
+ * @property {Meta} meta Parsed frontmatter for the file.
  */
 
 /**
  * Walk `routesRoot` and collect page routes, sorted and de-duplicated.
+ *
+ * Drafts are filtered HERE, at the one route-discovery chokepoint, so every
+ * downstream consumer (the build, `routes.json`, the sitemap, the RSS feed)
+ * only ever sees the post-filter list — a `draft: true` page can never leak. By
+ * default drafts are excluded; pass `{ includeDrafts: true }` (`darkmown dev`
+ * and `darkmown build --drafts`) to keep them. This is distinct from, and
+ * orthogonal to, the permanent `.`/`-`/`_` filename hiding above: hidden names
+ * are private forever; `draft:` is a toggleable, publish-when-ready gate.
  * @param {string} routesRoot Absolute path to `site/pages`.
+ * @param {{ includeDrafts?: boolean }} [options]
  * @returns {Route[]}
  */
-export function discoverRoutes(routesRoot) {
+export function discoverRoutes(routesRoot, options = {}) {
   if (!fs.existsSync(routesRoot)) return [];
   /** @type {Route[]} */
   const routes = [];
@@ -32,9 +50,12 @@ export function discoverRoutes(routesRoot) {
       if (!pageExtensions.has(ext)) continue;
       const base = path.basename(entry.name, ext);
       if (isHiddenName(base)) continue;
+      const { meta } = parseFrontmatter(fs.readFileSync(abs, "utf8"), abs);
+      if (isDraft(meta) && !options.includeDrafts) continue;
       routes.push({
         file: abs,
-        route: routeFromFile(routesRoot, abs)
+        route: routeFromFile(routesRoot, abs),
+        meta
       });
     }
   }
@@ -52,6 +73,17 @@ export function discoverRoutes(routesRoot) {
   return routes.sort((a, b) => a.route.localeCompare(b.route));
 }
 
+/**
+ * Whether a page's frontmatter marks it a draft (`draft: true`). The scalar
+ * frontmatter parser yields a boolean `true` or the string `"true"`, so accept
+ * both; any other value (absent, `false`, `"false"`) is not a draft.
+ * @param {Meta} meta
+ * @returns {boolean}
+ */
+export function isDraft(meta) {
+  return meta.draft === true || meta.draft === "true";
+}
+
 /**
  * Derive a public route path from a source file path.
  * @param {string} routesRoot Absolute path to `site/pages`.

package/src/skin.js

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+
 const aliases = new Map([
   ["radius", "border-radius"],
   ["shadow", "box-shadow"],
@@ -19,6 +21,29 @@ function resolveProp(prop, rest) {
   return aliases.get(prop) || prop;
 }
 
+/**
+ * Derive a short, deterministic scope id from a skin's PROJECT-RELATIVE PATH.
+ * Path-based (stable across content edits, unique per component file) and short
+ * enough to read in the emitted CSS (`wd-7c21`). The same path always yields the
+ * same id, so the CSS rewrite (builder) and the HTML stamp (page/include) agree
+ * without sharing state — they just hash the same relative path. The path is
+ * normalized to POSIX separators first so a build is identical on Windows.
+ * @param {string} relPath Skin path relative to the project root (cwd).
+ * @returns {string} The scope id, e.g. `wd-7c21`.
+ */
+export function scopeIdFor(relPath) {
+  const posix = relPath.replaceAll("\\", "/");
+  const hash = crypto.createHash("sha256").update(posix).digest("hex");
+  return `wd-${hash.slice(0, 4)}`;
+}
+
+// Selectors that style the whole page, not a component subtree. In a `scoped`
+// skin they are a mistake: scoping appends an attribute to the *subject* element,
+// so `page`/`body`/`html`/`*`/`::selection` would either become a no-op (no
+// element in the subtree carries the attribute on <body>/<html>) or silently
+// fail to do what the author means. We error and point them at a global skin.
+const PAGE_LEVEL_SELECTORS = new Set(["page", "*", "html", "body", "::selection"]);
+
 /**
  * A nesting frame in the indentation stack.
  * @typedef {object} SkinFrame
@@ -29,10 +54,25 @@ function resolveProp(prop, rest) {
 
 /**
  * Compile indentation-based `.skin` source into CSS.
+ *
+ * Scoping (opt-in): when `opts.scope` is set the skin is compiled in scoped
+ * mode — every selector RULE gets `[data-wd-scope="<id>"]` appended to the
+ * subject of each compound selector, so the stylesheet only ever matches inside
+ * the stamped subtree. Design tokens (`tokens` / `tokens dark` / `tokens [attr]`)
+ * stay GLOBAL on `:root` regardless, so `var(--x)` and dark mode keep working
+ * site-wide. A whole-selector `:global(.x)` escapes scoping. Page-level selectors
+ * (`page`/`*`/`html`/`body`/`::selection`) are a compile error in scoped mode.
+ * Without `opts.scope`, output is byte-identical to before this feature existed.
  * @param {string} source
+ * @param {{ scope?: string, subjects?: Set<string> }} [opts] `scope`: the scope
+ *   id enabling scoped mode. `subjects`: an optional set the compiler fills with
+ *   every scoped subject token (`.card`, `h2`, `#id`) for the unused-selector
+ *   warning, so the caller need not re-parse the source.
  * @returns {string}
  */
-export function compileSkin(source) {
+export function compileSkin(source, opts = {}) {
+  const scope = opts.scope;
+  const subjects = opts.subjects;
   const lines = source
     .replace(/\r\n?/g, "\n")
     .replace(/\/\*[\s\S]*?\*\//g, "") // strip /* … */ block comments (any span)
@@ -47,6 +87,19 @@ export function compileSkin(source) {
     })
     .map((raw) => ({ indent: (raw.match(/^\s*/)?.[0] ?? "").length, text: raw.trim() }));
 
+  // The opt-in marker: `scoped` must be the FIRST meaningful line (the filter
+  // above has already dropped comments, blanks, and dividers). Anywhere else it
+  // is an error — a `scoped` mid-file means the author misread the contract.
+  let start = 0;
+  if (scope && lines.length && lines[0].text === "scoped" && lines[0].indent === 0) {
+    start = 1;
+  }
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i].text === "scoped" && lines[i].indent === 0) {
+      throw new Error('"scoped" must be the first line of a .skin file');
+    }
+  }
+
   /** @type {SkinFrame[]} */
   const stack = [];
   /** @type {string[]} */
@@ -65,7 +118,7 @@ export function compileSkin(source) {
   /** @type {Map<string, string[]>} */
   const attrVars = new Map();
 
-  for (let i = 0; i < lines.length; i++) {
+  for (let i = start; i < lines.length; i++) {
     const { indent, text } = lines[i];
     // Structure decides meaning: a line opens a block (selector) exactly when
     // the next line is indented deeper. Everything else is a declaration.
@@ -119,17 +172,28 @@ export function compileSkin(source) {
       if (text.startsWith("@")) {
         stack.push({ indent, selector: parent ?? null, media: text });
       } else {
+        if (scope) guardPageLevel(text, parent);
         stack.push({ indent, selector: normalizeSelector(text, parent) });
       }
       continue;
     }
 
     const current = stack.at(-1)?.selector || ":root";
+    // A leaf with no enclosing selector lands on `:root` — a page-level write. In
+    // a scoped skin that is the same mistake `guardPageLevel` rejects (and the
+    // place a filtered bare `*`/`page` reset would otherwise leak through to), so
+    // it errors with the same hint instead of emitting a never-matching rule.
+    if (scope && current === ":root") {
+      throw new Error(
+        `page-level declaration "${text}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      );
+    }
     const media = stack.find((frame) => frame.media)?.media;
     const [prop, ...rest] = text.split(/\s+/);
     const cssProp = resolveProp(prop, rest);
     const value = rest.join(" ").replace(/\$([a-zA-Z0-9_-]+)/g, "var(--$1)");
-    const rule = `${current} { ${cssProp}: ${value}; }`;
+    const subject = scope ? scopeSelector(current, scope, subjects) : current;
+    const rule = `${subject} { ${cssProp}: ${value}; }`;
     css.push(media ? `${media} { ${rule} }` : rule);
   }
 
@@ -153,6 +217,86 @@ export function compileSkin(source) {
   return css.join("\n");
 }
 
+/**
+ * Reject page-level selectors in a scoped skin. Checks the AUTHORED selector
+ * text (before `page`→`body` rewrite) so `page` is caught by name. Each
+ * comma-separated part is inspected; a bare top-level selector (no parent) that
+ * is one of the page-level set, or a top-level `::selection`, errors with a hint
+ * pointing the author at a global skin.
+ * @param {string} text Raw selector line.
+ * @param {string | null | undefined} parent Enclosing selector, if nested.
+ * @returns {void}
+ */
+function guardPageLevel(text, parent) {
+  // Only TOP-LEVEL selectors are page-level mistakes — `.card *` (a descendant
+  // wildcard inside a component) is fine, so the check applies when there is no
+  // parent selector chain (`:root` is the implicit root, treated as none).
+  if (parent && parent !== ":root") return;
+  for (const part of text.split(",")) {
+    const clean = part.trim();
+    if (PAGE_LEVEL_SELECTORS.has(clean)) {
+      throw new Error(
+        `page-level selector "${clean}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      );
+    }
+  }
+}
+
+/**
+ * Append the scope attribute to a resolved selector list (post `&`-nesting).
+ * Each comma-separated compound selector gets `[data-wd-scope="<id>"]` on its
+ * SUBJECT (rightmost simple selector), inserted BEFORE any trailing
+ * pseudo-class/element so the result stays valid CSS (`.card[…]:hover`, never
+ * `.card:hover[…]`). A whole-selector `:global(.x)` unwraps to a plain `.x` with
+ * NO attribute — the documented escape hatch (whole-selector only this release).
+ * @param {string} selectorList Resolved selector list (may contain commas).
+ * @param {string} scope Scope id.
+ * @param {Set<string>} [subjects] Optional sink for subject tokens (warning).
+ * @returns {string}
+ */
+function scopeSelector(selectorList, scope, subjects) {
+  return selectorList
+    .split(",")
+    .map((part) => {
+      const clean = part.trim();
+      // Whole-selector `:global(.toast)` → `.toast`, unscoped. Descendant
+      // `:global` (`.card :global(.x)`) is intentionally NOT supported yet.
+      const global = clean.match(/^:global\(\s*(.+?)\s*\)$/);
+      if (global) return global[1];
+      // The subject is the last whitespace-delimited compound. Combinators
+      // (`>`, `+`, `~`) stand as their own tokens, so the subject is whatever
+      // follows the final combinator/descendant gap.
+      const tokens = clean.split(/\s+/);
+      const subjectIndex = tokens.length - 1;
+      const lead = tokens.slice(0, subjectIndex);
+      const subject = tokens[subjectIndex];
+      // Split the subject into its base (tag/class/id, plus attribute selectors)
+      // and any trailing pseudo `:hover` / `::before`. The attribute slots in at
+      // the base/pseudo seam: `.card::before` → `.card[scope]::before`.
+      const seam = subject.search(/::?[a-zA-Z-]/);
+      const base = seam === -1 ? subject : subject.slice(0, seam);
+      const pseudo = seam === -1 ? "" : subject.slice(seam);
+      if (subjects) subjects.add(subjectBase(base));
+      const scoped = `${base}[data-wd-scope="${scope}"]${pseudo}`;
+      return [...lead, scoped].join(" ");
+    })
+    .join(", ");
+}
+
+/**
+ * Reduce a scoped subject base to the single token the unused-selector warning
+ * checks against the stamped subtree: the leading `.class`, `#id`, or bare tag,
+ * dropping any chained attribute selectors (`a[href]` → `a`). Returns `""` for a
+ * subject that has no checkable token (a bare attribute selector), which the
+ * caller treats as "always present" (never warns).
+ * @param {string} base
+ * @returns {string}
+ */
+function subjectBase(base) {
+  const m = base.match(/^([.#]?[A-Za-z_][\w-]*)/);
+  return m ? m[1] : "";
+}
+
 /**
  * Normalize a bracketed token modifier into a valid attribute selector,
  * quoting the value so `[data-theme=dark]` becomes `[data-theme="dark"]`.

package/src/templates/blog/site/pages/index.wd

@@ -1,6 +1,7 @@
 ---
 title: My Blog
 description: A markdown-native blog built with Darkmown.
+site_url: https://example.com
 transitions: true
 ---
 

package/src/templates/blog/site/pages/posts/hello-darkmown.md

@@ -1,6 +1,8 @@
 ---
 title: Hello, Darkmown
 description: Why I rewrote my blog as plain Markdown files.
+date: 2026-01-15
+excerpt: I rewrote my blog as plain Markdown files — no React, no build ceremony, and it ships zero JavaScript.
 transitions: true
 ---
 

package/src/templates/blog/site/pages/posts/markdown-native.md

@@ -1,6 +1,8 @@
 ---
 title: Markdown-native, by default
 description: Every post is a .md file; the index is one .wd loop.
+date: 2026-02-02
+excerpt: Every post is a plain .md file; the index is one .wd loop. The date in each post's frontmatter is what lands it in rss.xml.
 transitions: true
 ---