build.js

#!/usr/bin/env node
// build.js — markdown -> HTML for workman.tech
//
// Walks _posts/<theme>/YYYY-MM-DD-slug.md, renders each post via _template.html,
// emits a per-theme landing page via _theme_template.html, and regenerates the
// post-list region inside index.html (between <!-- posts:start --> and
// <!-- posts:end --> marker comments). See CLAUDE.md for the workflow.

const fs = require("fs");
const path = require("path");
const matter = require("gray-matter");
const MarkdownIt = require("markdown-it");
const prettier = require("prettier");

const ROOT = __dirname;
const POSTS_DIR = path.join(ROOT, "_posts");
const POST_TEMPLATE_PATH = path.join(ROOT, "_template.html");
const THEME_TEMPLATE_PATH = path.join(ROOT, "_theme_template.html");
const INDEX_PATH = path.join(ROOT, "index.html");
const SITEMAP_PATH = path.join(ROOT, "sitemap.xml");
const GENERATED_MARKER = "<!-- generated by build.js -->";
const POSTS_START = "<!-- posts:start -->";
const POSTS_END = "<!-- posts:end -->";
const SITE_ORIGIN = "https://workman.tech";
// Stable @id anchors for the structured-data entity graph. The full Person and
// WebSite nodes are defined once on the homepage (index.html); posts reference
// them by these ids so the whole site resolves to one author entity.
const PERSON_ID = `${SITE_ORIGIN}/#person`;
const WEBSITE_ID = `${SITE_ORIGIN}/#website`;
const DEFAULT_DESCRIPTION =
  "Ryan Workman's corner of the web. Senior full-stack dev (~10 years, mostly Rails and JS, Turing grad) writing about what he's building and learning.";

const md = new MarkdownIt({
  html: true,
  linkify: true,
  typographer: true,
});

// Open links authored in post markdown in a new tab. This applies ONLY to
// links written in the .md source — the site's own navigation links (back
// links, theme/post-list links) are built as plain strings elsewhere and
// stay in the same tab. rel="noopener" is the required security partner for
// target="_blank" (blocks reverse tabnabbing).
const defaultLinkOpen =
  md.renderer.rules.link_open ||
  ((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options));
md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
  tokens[idx].attrSet("target", "_blank");
  tokens[idx].attrSet("rel", "noopener");
  return defaultLinkOpen(tokens, idx, options, env, self);
};

// ---------- helpers ----------

const FILENAME_RE = /^(\d{4})-(\d{2})-(\d{2})-([a-z0-9][a-z0-9-]*)\.md$/i;

function die(msg) {
  console.error(`build.js: ${msg}`);
  process.exit(1);
}

function warn(msg) {
  console.warn(`build.js: warning: ${msg}`);
}

function escapeHtml(str) {
  return String(str)
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#39;");
}

function escapeAttr(str) {
  return escapeHtml(str);
}

function titleCase(slug) {
  return slug
    .split(/[-_]/)
    .filter(Boolean)
    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
    .join(" ");
}

const MONTH_NAMES = [
  "january",
  "february",
  "march",
  "april",
  "may",
  "june",
  "july",
  "august",
  "september",
  "october",
  "november",
  "december",
];

function ordinal(n) {
  const j = n % 10;
  const k = n % 100;
  if (k >= 11 && k <= 13) return `${n}th`;
  if (j === 1) return `${n}st`;
  if (j === 2) return `${n}nd`;
  if (j === 3) return `${n}rd`;
  return `${n}th`;
}

function formatDateDisplay(isoDate) {
  // isoDate is "YYYY-MM-DD"
  const [y, m, d] = isoDate.split("-").map(Number);
  return `${MONTH_NAMES[m - 1]} ${ordinal(d)}, ${y}`;
}

function toIsoDate(value) {
  // gray-matter parses YAML dates into JS Date objects. Normalize to YYYY-MM-DD
  // in UTC so we don't get timezone drift on the user's machine.
  if (value instanceof Date) {
    const y = value.getUTCFullYear();
    const m = String(value.getUTCMonth() + 1).padStart(2, "0");
    const d = String(value.getUTCDate()).padStart(2, "0");
    return `${y}-${m}-${d}`;
  }
  if (typeof value === "string") {
    // Accept either "YYYY-MM-DD" or a full ISO string
    const m = value.match(/^(\d{4})-(\d{2})-(\d{2})/);
    if (m) return `${m[1]}-${m[2]}-${m[3]}`;
  }
  return null;
}

function applyTemplate(template, vars) {
  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
    if (!(key in vars)) {
      throw new Error(`template missing variable: ${key}`);
    }
    return vars[key];
  });
}

// ---------- post discovery ----------

// _posts/drafts/ is a local, gitignored staging area for work-in-progress
// drafts (e.g. imported from work notes). It is never rendered to the site —
// a draft gets moved into a real theme folder once it's ready to publish, at
// which point it starts building normally. Excluding it here keeps the staging
// area from leaking onto the homepage or generating a public /drafts/ dir.
const EXCLUDED_THEME_DIRS = new Set(["drafts"]);

function listThemeDirs() {
  if (!fs.existsSync(POSTS_DIR)) return [];
  return fs
    .readdirSync(POSTS_DIR, { withFileTypes: true })
    .filter((e) => e.isDirectory())
    .map((e) => e.name)
    .filter(
      (name) =>
        !name.startsWith("_") &&
        !name.startsWith(".") &&
        !EXCLUDED_THEME_DIRS.has(name),
    )
    .sort();
}

function loadPostsForTheme(themeSlug) {
  const themeDir = path.join(POSTS_DIR, themeSlug);
  const entries = fs.readdirSync(themeDir, { withFileTypes: true });
  const posts = [];
  for (const entry of entries) {
    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
    const match = entry.name.match(FILENAME_RE);
    if (!match) {
      die(
        `invalid post filename: _posts/${themeSlug}/${entry.name} — expected YYYY-MM-DD-slug.md`,
      );
    }
    const [, y, m, d, slug] = match;
    const filenameDate = `${y}-${m}-${d}`;
    const filePath = path.join(themeDir, entry.name);
    const raw = fs.readFileSync(filePath, "utf8");
    const parsed = matter(raw);
    const fm = parsed.data || {};

    if (!fm.title || typeof fm.title !== "string") {
      die(
        `missing or invalid 'title' in frontmatter: _posts/${themeSlug}/${entry.name}`,
      );
    }
    if (fm.date == null) {
      die(`missing 'date' in frontmatter: _posts/${themeSlug}/${entry.name}`);
    }
    const fmDate = toIsoDate(fm.date);
    if (!fmDate) {
      die(
        `invalid 'date' in frontmatter (expected YYYY-MM-DD): _posts/${themeSlug}/${entry.name}`,
      );
    }
    if (fmDate !== filenameDate) {
      warn(
        `frontmatter date (${fmDate}) differs from filename date (${filenameDate}) for _posts/${themeSlug}/${entry.name} — using frontmatter`,
      );
    }
    const tags = Array.isArray(fm.tags) ? fm.tags.map((t) => String(t)) : [];
    const description =
      typeof fm.description === "string" && fm.description.trim()
        ? fm.description.trim()
        : null;

    // Series support: a theme folder is treated as a "series" when every post
    // in it carries an integer `part`. `series` is the human-readable display
    // title used for the section heading and landing page. Both are optional;
    // a theme with no `part` fields keeps the default date-descending behavior.
    const series =
      typeof fm.series === "string" && fm.series.trim()
        ? fm.series.trim()
        : null;
    let part = null;
    if (fm.part != null) {
      if (typeof fm.part === "number" && Number.isInteger(fm.part)) {
        part = fm.part;
      } else {
        die(
          `invalid 'part' in frontmatter (expected an integer): _posts/${themeSlug}/${entry.name}`,
        );
      }
    }

    posts.push({
      themeSlug,
      themeDisplay: titleCase(themeSlug),
      slug,
      filename: `${filenameDate}-${slug}.html`,
      sourcePath: filePath,
      sourceRel: `_posts/${themeSlug}/${entry.name}`,
      date: fmDate,
      title: fm.title.trim(),
      description,
      tags,
      series,
      part,
      bodyMarkdown: parsed.content,
    });
  }
  return posts;
}

function collectAllPosts() {
  const themes = listThemeDirs();
  const byTheme = new Map();
  let total = 0;
  for (const theme of themes) {
    const posts = loadPostsForTheme(theme);
    if (isSeriesPosts(posts)) {
      // A series reads intro-first, so order by part ascending (tiebreak on
      // date then slug) rather than the newest-first default below.
      posts.sort(
        (a, b) =>
          a.part - b.part ||
          (a.date < b.date
            ? -1
            : a.date > b.date
              ? 1
              : a.slug.localeCompare(b.slug)),
      );
    } else {
      posts.sort((a, b) =>
        a.date < b.date
          ? 1
          : a.date > b.date
            ? -1
            : a.slug.localeCompare(b.slug),
      );
    }
    if (posts.length > 0) {
      byTheme.set(theme, posts);
      total += posts.length;
    }
  }
  return { byTheme, total };
}

// ---------- rendering ----------

function renderPostBody(post) {
  return md.render(post.bodyMarkdown);
}

// Format generated HTML with Prettier so committed output is consistent and
// deterministic. Async because Prettier v3's format() returns a Promise.
// Options are passed explicitly (no .prettierrc lookup) to keep the build
// self-contained and reproducible in CI.
async function formatHtml(html) {
  return prettier.format(html, { parser: "html" });
}

function renderTagPills(tags) {
  if (!tags || tags.length === 0) return "";
  const pills = tags
    .map((t) => `<span class="tag">${escapeHtml(t)}</span>`)
    .join("");
  return `<span class="tags">${pills}</span>`;
}

function themeAndTagsLine(post) {
  const themeLink = `<a href="/${post.themeSlug}/">${escapeHtml(
    post.themeDisplay,
  )}</a>`;
  if (post.tags.length === 0) return themeLink;
  return `${themeLink} · ${renderTagPills(post.tags)}`;
}

function canonicalUrlForPost(post) {
  return `${SITE_ORIGIN}/${post.themeSlug}/${post.filename}`;
}

function canonicalUrlForTheme(themeSlug) {
  return `${SITE_ORIGIN}/${themeSlug}/`;
}

// A theme folder is a "series" when every post in it declares an integer part.
function isSeriesPosts(posts) {
  return posts.length > 0 && posts.every((p) => p.part != null);
}

// Section/landing heading for a theme: the series display title when it's a
// series, otherwise the title-cased folder name.
function sectionTitleFor(themeSlug, posts) {
  return isSeriesPosts(posts) && posts[0].series
    ? posts[0].series
    : titleCase(themeSlug);
}

// "Part N" kicker for a post-item, only inside a series listing.
function partLabel(post, inSeries) {
  return inSeries && post.part != null
    ? `\n            <span class="post-part">Part ${post.part}</span>`
    : "";
}

// Serialize an object as a JSON-LD <script> block. JSON embedded in <script>
// must not contain a literal </script>, so we escape <, >, & to their \uXXXX
// forms after stringifying. This is deliberately NOT escapeHtml — that would
// corrupt the JSON (e.g. turn " into &quot;); JSON.stringify already handles
// escaping of the values themselves.
function jsonLdScript(obj) {
  const json = JSON.stringify(obj, null, 2)
    .replace(/</g, "\\u003c")
    .replace(/>/g, "\\u003e")
    .replace(/&/g, "\\u0026");
  return `<script type="application/ld+json">\n${json}\n</script>`;
}

// Per-post BlogPosting structured data. author/publisher reference the Person
// node defined on the homepage by @id, and isPartOf references the WebSite,
// so the whole site resolves to one author entity. Dates come from frontmatter
// only (keeps the build deterministic — same rule as the sitemap).
function renderPostJsonLd(post, description) {
  const url = canonicalUrlForPost(post);
  const obj = {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    headline: post.title,
    description,
    datePublished: post.date,
    dateModified: post.date,
    url,
    mainEntityOfPage: url,
    inLanguage: "en",
  };
  if (post.tags.length > 0) obj.keywords = post.tags;
  obj.isPartOf = { "@id": WEBSITE_ID };
  obj.author = { "@type": "Person", "@id": PERSON_ID, name: "Ryan Workman" };
  obj.publisher = { "@id": PERSON_ID };
  return jsonLdScript(obj);
}

function renderPost(template, post) {
  const description = post.description || DEFAULT_DESCRIPTION;
  const content = renderPostBody(post);
  return applyTemplate(template, {
    title: escapeHtml(post.title),
    description: escapeAttr(description),
    canonical_url: escapeAttr(canonicalUrlForPost(post)),
    date_display: escapeHtml(formatDateDisplay(post.date)),
    date_iso: post.date,
    theme_display: escapeHtml(post.themeDisplay),
    theme_slug: post.themeSlug,
    tags_display: post.tags.map(escapeHtml).join(", "),
    theme_and_tags_line: themeAndTagsLine(post),
    json_ld: renderPostJsonLd(post, description),
    content,
  });
}

function renderThemeListing(template, themeSlug, posts) {
  const inSeries = isSeriesPosts(posts);
  const heading = sectionTitleFor(themeSlug, posts);
  const description = inSeries
    ? `the "${heading}" series by Ryan Workman`
    : `${heading} writing by Ryan Workman`;
  const items = posts
    .map((p) => {
      const href = `/${p.themeSlug}/${p.filename}`;
      const partLine = partLabel(p, inSeries);
      const tagLine =
        p.tags.length > 0 ? `\n            ${renderTagPills(p.tags)}` : "";
      const desc = p.description
        ? `\n            <p class="post-desc">${escapeHtml(p.description)}</p>`
        : "";
      return (
        `          <li class="post-item">${partLine}\n` +
        `            <a class="post-title" href="${escapeAttr(href)}">${escapeHtml(
          p.title,
        )}</a>\n` +
        `            <time class="post-date" datetime="${p.date}">${escapeHtml(
          formatDateDisplay(p.date),
        )}</time>${desc}${tagLine}\n` +
        `          </li>`
      );
    })
    .join("\n");
  const postList =
    posts.length === 0
      ? `          <p><em>No posts yet.</em></p>`
      : `          <ul class="post-list">\n${items}\n          </ul>`;
  return applyTemplate(template, {
    theme_display: escapeHtml(heading),
    description: escapeAttr(description),
    canonical_url: escapeAttr(canonicalUrlForTheme(themeSlug)),
    post_list: postList,
  });
}

function renderHomepagePostList(byTheme) {
  if (byTheme.size === 0) {
    return `        <p><em>New posts coming soon.</em></p>`;
  }
  // Series sections float above topic themes (a curated reading path outranks a
  // topic bucket); alphabetical within each group.
  const themeNames = Array.from(byTheme.keys()).sort((a, b) => {
    const aSeries = isSeriesPosts(byTheme.get(a));
    const bSeries = isSeriesPosts(byTheme.get(b));
    if (aSeries !== bSeries) return aSeries ? -1 : 1;
    return a.localeCompare(b);
  });
  const sections = themeNames.map((themeSlug) => {
    const posts = byTheme.get(themeSlug);
    const inSeries = isSeriesPosts(posts);
    const heading = sectionTitleFor(themeSlug, posts);
    const items = posts
      .map((p) => {
        const href = `/${p.themeSlug}/${p.filename}`;
        const partLine = partLabel(p, inSeries);
        const tagLine =
          p.tags.length > 0 ? `\n            ${renderTagPills(p.tags)}` : "";
        return (
          `          <li class="post-item">${partLine}\n` +
          `            <a class="post-title" href="${escapeAttr(href)}">${escapeHtml(
            p.title,
          )}</a>\n` +
          `            <time class="post-date" datetime="${p.date}">${escapeHtml(
            formatDateDisplay(p.date),
          )}</time>${tagLine}\n` +
          `          </li>`
        );
      })
      .join("\n");
    return (
      `        <h2 class="post-section-title"><a href="/${themeSlug}/">${escapeHtml(
        heading,
      )}</a></h2>\n` + `        <ul class="post-list">\n${items}\n        </ul>`
    );
  });
  return sections.join("\n");
}

async function regenerateIndex(byTheme) {
  if (!fs.existsSync(INDEX_PATH)) {
    die(`index.html not found at ${INDEX_PATH}`);
  }
  const current = fs.readFileSync(INDEX_PATH, "utf8");
  const startIdx = current.indexOf(POSTS_START);
  const endIdx = current.indexOf(POSTS_END);
  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
    die(
      `index.html is missing required marker comments ` +
        `(${POSTS_START} ... ${POSTS_END}) around the post-list region`,
    );
  }
  const before = current.slice(0, startIdx + POSTS_START.length);
  const after = current.slice(endIdx);
  const region = `\n${renderHomepagePostList(byTheme)}\n        `;
  const next = await formatHtml(`${before}${region}${after}`);
  if (next !== current) {
    fs.writeFileSync(INDEX_PATH, next);
  }
}

// ---------- sitemap ----------

// Build sitemap.xml: the homepage, every theme landing page, and every post.
// <lastmod> is derived only from frontmatter dates (never build time), so the
// output is byte-stable and CI's "git clean after build" check holds. Not run
// through Prettier — Prettier core has no XML parser — so the formatting here
// is the committed formatting. URL order is deterministic: homepage, then
// themes in the byTheme map's (alphabetical) order, each landing page followed
// by its posts.
function renderSitemap(byTheme) {
  const entries = [];
  let newestOverall = null;
  for (const posts of byTheme.values()) {
    for (const p of posts) {
      if (!newestOverall || p.date > newestOverall) newestOverall = p.date;
    }
  }
  entries.push({ loc: `${SITE_ORIGIN}/`, lastmod: newestOverall });
  for (const [themeSlug, posts] of byTheme) {
    let newestInTheme = null;
    for (const p of posts) {
      if (!newestInTheme || p.date > newestInTheme) newestInTheme = p.date;
    }
    entries.push({
      loc: canonicalUrlForTheme(themeSlug),
      lastmod: newestInTheme,
    });
    for (const p of posts) {
      entries.push({ loc: canonicalUrlForPost(p), lastmod: p.date });
    }
  }
  const body = entries
    .map(({ loc, lastmod }) => {
      const lastmodLine = lastmod ? `\n    <lastmod>${lastmod}</lastmod>` : "";
      return `  <url>\n    <loc>${escapeHtml(loc)}</loc>${lastmodLine}\n  </url>`;
    })
    .join("\n");
  return (
    `<?xml version="1.0" encoding="UTF-8"?>\n` +
    `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n` +
    `${body}\n` +
    `</urlset>\n`
  );
}

// ---------- cleaning ----------

// Reserved top-level entries that we must never treat as generated theme
// output directories, even if a future hand-edit accidentally adds a stub
// HTML file with the generated marker inside.
const RESERVED_DIR_NAMES = new Set([
  "_posts",
  "css",
  "images",
  "js",
  "node_modules",
  ".git",
  ".github",
  ".claude",
]);

function isGeneratedHtmlDir(dir) {
  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  // Refuse if there are any subdirectories — generated theme dirs are flat.
  if (entries.some((e) => e.isDirectory())) return false;
  const htmlFiles = entries.filter(
    (e) => e.isFile() && e.name.endsWith(".html"),
  );
  if (htmlFiles.length === 0) return false;
  // All files in the directory must be HTML, and every HTML file must start
  // with the generated marker. Anything else means this is hand-edited.
  if (entries.some((e) => e.isFile() && !e.name.endsWith(".html")))
    return false;
  return htmlFiles.every((e) => {
    const content = fs.readFileSync(path.join(dir, e.name), "utf8");
    return content.startsWith(GENERATED_MARKER);
  });
}

function findGeneratedDirs() {
  return fs
    .readdirSync(ROOT, { withFileTypes: true })
    .filter((e) => e.isDirectory())
    .map((e) => e.name)
    .filter((name) => !name.startsWith(".") && !RESERVED_DIR_NAMES.has(name))
    .filter((name) => isGeneratedHtmlDir(path.join(ROOT, name)));
}

function removeStaleThemeDirs(activeThemes) {
  let removed = 0;
  for (const name of findGeneratedDirs()) {
    if (activeThemes.has(name)) continue;
    fs.rmSync(path.join(ROOT, name), { recursive: true, force: true });
    removed += 1;
  }
  return removed;
}

async function cleanGeneratedDirs() {
  const generated = findGeneratedDirs();
  for (const name of generated) {
    fs.rmSync(path.join(ROOT, name), { recursive: true, force: true });
  }
  // Also remove the generated sitemap and reset the index post-list region.
  fs.rmSync(SITEMAP_PATH, { force: true });
  if (fs.existsSync(INDEX_PATH)) {
    await regenerateIndex(new Map());
  }
  console.log(
    `clean: removed ${generated.length} generated theme director${generated.length === 1 ? "y" : "ies"}${generated.length ? ` (${generated.join(", ")})` : ""}.`,
  );
}

// ---------- main ----------

async function build() {
  if (!fs.existsSync(POST_TEMPLATE_PATH)) {
    die(`missing template: ${POST_TEMPLATE_PATH}`);
  }
  if (!fs.existsSync(THEME_TEMPLATE_PATH)) {
    die(`missing template: ${THEME_TEMPLATE_PATH}`);
  }
  const postTemplate = fs.readFileSync(POST_TEMPLATE_PATH, "utf8");
  const themeTemplate = fs.readFileSync(THEME_TEMPLATE_PATH, "utf8");

  const { byTheme, total } = collectAllPosts();

  const activeThemes = new Set(byTheme.keys());
  const staleRemoved = removeStaleThemeDirs(activeThemes);
  if (staleRemoved > 0) {
    console.log(
      `build: removed ${staleRemoved} stale theme director${staleRemoved === 1 ? "y" : "ies"}.`,
    );
  }

  for (const [themeSlug, posts] of byTheme) {
    const outDir = path.join(ROOT, themeSlug);
    fs.mkdirSync(outDir, { recursive: true });
    const expectedFiles = new Set(posts.map((p) => p.filename));
    expectedFiles.add("index.html");
    // Remove any stale generated HTML files (posts that were deleted) — but
    // only files that look like build output (start with the generated marker),
    // never touch anything hand-edited.
    for (const entry of fs.readdirSync(outDir, { withFileTypes: true })) {
      if (!entry.isFile() || !entry.name.endsWith(".html")) continue;
      if (expectedFiles.has(entry.name)) continue;
      const filePath = path.join(outDir, entry.name);
      const head = fs
        .readFileSync(filePath, "utf8")
        .slice(0, GENERATED_MARKER.length);
      if (head === GENERATED_MARKER) {
        fs.unlinkSync(filePath);
      } else {
        warn(`leaving non-generated file in place: ${themeSlug}/${entry.name}`);
      }
    }
    for (const post of posts) {
      const html = await formatHtml(renderPost(postTemplate, post));
      fs.writeFileSync(path.join(outDir, post.filename), html);
    }
    const listingHtml = await formatHtml(
      renderThemeListing(themeTemplate, themeSlug, posts),
    );
    fs.writeFileSync(path.join(outDir, "index.html"), listingHtml);
  }

  await regenerateIndex(byTheme);
  fs.writeFileSync(SITEMAP_PATH, renderSitemap(byTheme));

  const themeCount = byTheme.size;
  console.log(
    `build: ${total} post${total === 1 ? "" : "s"} across ${themeCount} theme${
      themeCount === 1 ? "" : "s"
    }.`,
  );
  if (themeCount > 0) {
    for (const [themeSlug, posts] of byTheme) {
      console.log(`  ${themeSlug}/ (${posts.length})`);
    }
  }
}

async function main() {
  const args = process.argv.slice(2);
  if (args.includes("--clean")) {
    await cleanGeneratedDirs();
    return;
  }
  await build();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});