@zvndev/darkmown 1.2.0 → 1.3.0

package/src/feeds.js

@@ -0,0 +1,276 @@
+// ---------------------------------------------------------------------------
+// Feeds & crawler files: sitemap.xml, rss.xml, robots.txt. All build-time only
+// (zero runtime, zero client JS) and emitted from the post-draft-filter route
+// list, so a `draft: true` page never reaches a feed. Site identity (origin,
+// channel title/description) lives in the HOME page frontmatter (`site_url` +
+// the existing `title`/`description`) — there is no config loader this cycle.
+//
+// Mirrors `src/highlight.js`: this module owns the strings; `src/builder.js`
+// owns the emission. Pure string builders + a `lastmodFor(file)` with a
+// git → mtime fallback so scaffolded apps / tarballs (no git repo) still date.
+// ---------------------------------------------------------------------------
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {import("./router.js").Route} Route
+ */
+
+/**
+ * A route paired with its source file's last-modified date (ISO yyyy-mm-dd),
+ * ready for a sitemap `<lastmod>`.
+ * @typedef {object} DatedRoute
+ * @property {string} loc Absolute URL (`site_url` + route path).
+ * @property {string} lastmod ISO date (`yyyy-mm-dd`).
+ */
+
+/**
+ * XML-escape a text value for use inside an element or attribute. Covers the
+ * five predefined XML entities — the same set RSS/sitemap consumers expect.
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeXml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/**
+ * Join the site origin and a route path into one absolute URL, collapsing the
+ * boundary slash so `https://x.com` + `/about/` → `https://x.com/about/` (the
+ * home route `/` → `https://x.com/`). `siteUrl` is expected without a trailing
+ * slash (the documented contract); a stray one is tolerated.
+ * @param {string} siteUrl Absolute origin, e.g. `https://example.com`.
+ * @param {string} route Route path (always trailing-slashed, e.g. `/about/`).
+ * @returns {string}
+ */
+export function absoluteUrl(siteUrl, route) {
+  return `${siteUrl.replace(/\/$/, "")}${route}`;
+}
+
+/**
+ * The last-modified date for a source file, as an ISO `yyyy-mm-dd` string.
+ * Resolution order: the file's frontmatter `date:` is handled by the caller
+ * (it wins); this helper covers the fallback chain — the git last-commit date
+ * of the file, else the filesystem mtime. Git is wrapped in try/catch so a
+ * scaffolded app or an extracted tarball (no `.git`) degrades to mtime instead
+ * of crashing the build.
+ * @param {string} file Absolute path to the source file.
+ * @returns {string} ISO date (`yyyy-mm-dd`).
+ */
+export function lastmodFor(file) {
+  try {
+    // `%cs` is the committer date in strict ISO short form (yyyy-mm-dd). `-1`
+    // limits to the most recent commit touching this file. A file that is
+    // tracked but never committed (or outside a repo) yields empty stdout.
+    const out = execFileSync("git", ["log", "-1", "--format=%cs", "--", path.basename(file)], {
+      cwd: path.dirname(file),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (out) return out;
+  } catch {
+    /* not a git repo, or git unavailable — fall through to mtime */
+  }
+  return isoDate(fs.statSync(file).mtime);
+}
+
+/**
+ * Format a `Date` as an ISO `yyyy-mm-dd` string (sitemap `<lastmod>` form).
+ * @param {Date} date
+ * @returns {string}
+ */
+export function isoDate(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+const RFC822_DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const RFC822_MONTHS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec"
+];
+
+/**
+ * Format a frontmatter `date:` value as an RFC-822 date for an RSS `<pubDate>`
+ * (e.g. `Sat, 28 Jun 2026 00:00:00 GMT`). Accepts anything `new Date` parses
+ * (an ISO `yyyy-mm-dd`, a full timestamp); an unparseable value returns "" so
+ * the caller can omit the element rather than emit `Invalid Date`.
+ * @param {string} value Raw frontmatter date string.
+ * @returns {string} RFC-822 date in GMT, or "" when unparseable.
+ */
+export function rfc822(value) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+  const pad = (/** @type {number} */ n) => String(n).padStart(2, "0");
+  const day = RFC822_DAYS[date.getUTCDay()];
+  const month = RFC822_MONTHS[date.getUTCMonth()];
+  return (
+    `${day}, ${pad(date.getUTCDate())} ${month} ${date.getUTCFullYear()} ` +
+    `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} GMT`
+  );
+}
+
+/**
+ * Read a frontmatter field as a trimmed string, or "" when absent/non-string
+ * (arrays, numbers, booleans don't belong in these single-value feed fields).
+ * @param {import("./compiler.js").Meta} meta
+ * @param {string} key
+ * @returns {string}
+ */
+function metaString(meta, key) {
+  const value = meta[key];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * Extract the first paragraph of a plain-`.md` body as a single-line snippet —
+ * the RSS description fallback when a `.md` post has neither `excerpt:` nor
+ * `description:`. Deliberately dumb: skip leading blank/frontmatter-less lines,
+ * take the first run of non-blank prose, strip the most common inline markdown
+ * (heading marks, emphasis, inline-code, links → their text), and collapse
+ * whitespace. Returns "" when the body is empty or starts with a non-prose
+ * block (a fence/heading-only doc) — the caller then falls back further.
+ * @param {string} body The post-frontmatter markdown body.
+ * @returns {string}
+ */
+export function firstParagraph(body) {
+  const lines = body.replace(/\r\n?/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++;
+  // A heading or fenced block isn't a description paragraph — bail to the
+  // caller's next fallback rather than emit "# Title" or code as the summary.
+  if (i >= lines.length || /^(#{1,6}\s|```|~~~|>|[-*+]\s|\d+\.\s)/.test(lines[i].trim())) return "";
+  /** @type {string[]} */
+  const collected = [];
+  for (let j = i; j < lines.length && lines[j].trim(); j++) collected.push(lines[j].trim());
+  return collected
+    .join(" ")
+    .replace(/`([^`]+)`/g, "$1") // inline code → its text
+    .replace(/\*\*([^*]+)\*\*/g, "$1") // bold
+    .replace(/\*([^*]+)\*/g, "$1") // italic
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) → text
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * The RSS `<description>` for a post: explicit `excerpt:` wins, else the source
+ * `description:`, else (plain `.md` only) the first rendered paragraph. `.wd`
+ * bodies are NOT scanned for a first paragraph — stripping reactive/directive
+ * markup back to clean prose is not worth the fragility, so a `.wd` post without
+ * `excerpt`/`description` simply gets no description.
+ * @param {import("./compiler.js").Meta} meta
+ * @param {string} file Absolute source path (its extension gates `.md` scanning).
+ * @param {string} body The post-frontmatter body.
+ * @returns {string}
+ */
+export function rssDescription(meta, file, body) {
+  const excerpt = metaString(meta, "excerpt");
+  if (excerpt) return excerpt;
+  const description = metaString(meta, "description");
+  if (description) return description;
+  if (path.extname(file) === ".md") return firstParagraph(body);
+  return "";
+}
+
+/**
+ * Build `sitemap.xml` from the emitted (post-draft-filter) routes. One `<url>`
+ * per route — reactive pages included (they're indexable HTML) — with `<loc>` =
+ * `site_url` + path and `<lastmod>` from the supplied date. The `/404/` route is
+ * excluded by the caller before this point. No `<priority>`/`<changefreq>` —
+ * Google ignores them and they invite bit-rot.
+ * @param {DatedRoute[]} entries Absolute loc + ISO lastmod, in route order.
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildSitemap(entries) {
+  const urls = entries
+    .map(
+      (entry) =>
+        `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>\n` +
+        `    <lastmod>${entry.lastmod}</lastmod>\n  </url>`
+    )
+    .join("\n");
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    `${urls}\n</urlset>\n`
+  );
+}
+
+/**
+ * An RSS item — a dated post in feed order.
+ * @typedef {object} RssItem
+ * @property {string} title
+ * @property {string} link Absolute URL (also used as the `<guid>`).
+ * @property {string} pubDate RFC-822 date, or "" to omit.
+ * @property {string} description
+ */
+
+/**
+ * Build `rss.xml` (RSS 2.0) for the dated posts. The caller selects, sorts
+ * (date desc), and caps the items; this builder just renders. Channel `<title>`
+ * / `<description>` come from the home frontmatter; `<link>` is the site origin
+ * and the `<atom:link rel="self">` points at the feed itself (RSS best practice).
+ * @param {{ title: string, description: string, siteUrl: string, feedUrl: string }} channel
+ * @param {RssItem[]} items
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildRss(channel, items) {
+  const entries = items.map((item) => {
+    const parts = [
+      `      <title>${escapeXml(item.title)}</title>`,
+      `      <link>${escapeXml(item.link)}</link>`,
+      `      <guid isPermaLink="true">${escapeXml(item.link)}</guid>`
+    ];
+    if (item.pubDate) parts.push(`      <pubDate>${item.pubDate}</pubDate>`);
+    if (item.description)
+      parts.push(`      <description>${escapeXml(item.description)}</description>`);
+    return `    <item>\n${parts.join("\n")}\n    </item>`;
+  });
+  const channelLines = [
+    `    <title>${escapeXml(channel.title)}</title>`,
+    `    <link>${escapeXml(channel.siteUrl)}</link>`,
+    `    <description>${escapeXml(channel.description)}</description>`,
+    `    <atom:link href="${escapeXml(channel.feedUrl)}" rel="self" type="application/rss+xml"/>`,
+    ...entries
+  ];
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">\n' +
+    "  <channel>\n" +
+    `${channelLines.join("\n")}\n` +
+    "  </channel>\n</rss>\n"
+  );
+}
+
+/**
+ * Build `robots.txt`. Always allows everything (hidden/draft routes are never
+ * built, so there's nothing to `Disallow`). The `Sitemap:` line is included
+ * ONLY when `siteUrl` is set — a sitemap URL is only meaningful with an origin.
+ * @param {string} [siteUrl] Absolute origin, or "" / undefined to omit the line.
+ * @returns {string} The robots.txt body (trailing newline).
+ */
+export function buildRobots(siteUrl) {
+  const lines = ["User-agent: *", "Allow: /"];
+  if (siteUrl) lines.push(`Sitemap: ${absoluteUrl(siteUrl, "/sitemap.xml")}`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** Most-recent-first RSS post cap — a feed is a recent window, not an archive. */
+export const RSS_ITEM_LIMIT = 20;

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/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
 ---