site: build starter stack pages and link them from the homepage, entries, sitemap and llms files

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Wc67NX9MM964uaVGn4bpZJ

Author: TMHSDigital

site/build.mjs

@@ -12,6 +12,9 @@ import { LinkError, makeLinkResolver } from "./lib/links.mjs";
 import { llmsFullTxt, llmsTxt } from "./lib/llms.mjs";
 import { deprecationReason, MarkdownError, renderBlocks, renderInline, splitEntryBody } from "./lib/markdown.mjs";
 import { checkPage } from "./lib/page-checks.mjs";
+import { checkStacks } from "./checks.mjs";
+import { stackPageHtml } from "./lib/stack-page.mjs";
+import { licenceTerms, owes, parseStack, pickPath } from "./lib/stacks.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, "..");
@@ -20,6 +23,8 @@ const PUBLIC = path.join(__dirname, "public");
 const DIST = path.join(__dirname, "dist");
 const CONFIG_PATH = path.join(__dirname, "config.json");
 const VOCAB_PATH = path.join(__dirname, "license-vocabulary.json");
+const SPDX_ALLOWED_PATH = path.join(__dirname, "spdx-allowed.json");
+const STACKS = path.join(ROOT, "stacks");
 // Social preview image: a first-party screenshot of this site, kept with the
 // other first-party stills (the validator allows binaries there) and copied
 // into dist at build time.
@@ -329,10 +334,11 @@ function headMetaHtml(site, stats, generatedAt, hasCard) {
   ].join("\n    ");
 }
 
-function sitemapXml(site, entries) {
+function sitemapXml(site, entries, stacks = []) {
   const base = site.siteUrl.replace(/\/+$/, "");
   const urls = [
     `  <url><loc>${esc(base)}/</loc></url>`,
+    ...stacks.map((s) => `  <url><loc>${esc(base)}/stack/${esc(s.meta.id)}/</loc><lastmod>${esc(s.meta.walked)}</lastmod></url>`),
     ...entries.map(
       (e) =>
         `  <url><loc>${esc(base)}/entry/${esc(e.id)}/</loc>${e.verified ? `<lastmod>${esc(e.verified)}</lastmod>` : ""}</url>`
@@ -382,19 +388,87 @@ function copyDir(src, dest) {
   }
 }
 
-/** Returns entry => link resolver for links in that entry's body. */
-function linkResolvers(entries, config) {
+/** Returns file => link resolver for links in that file's body (`file.path` is repo-relative). */
+function linkResolvers(entries, config, entryBase = "../") {
   const idByPath = new Map(entries.map((e) => [e.path, e.id]));
   const kindOf = (repoPath) => {
     const full = path.join(ROOT, repoPath);
     if (!fs.existsSync(full)) return null;
     return fs.statSync(full).isDirectory() ? "dir" : "file";
   };
-  return (entry) => makeLinkResolver({ entryPath: entry.path, idByPath, repo: config.site.repo, kindOf });
+  return (file) => makeLinkResolver({ entryPath: file.path, idByPath, repo: config.site.repo, kindOf, entryBase });
+}
+
+/** Reads stacks/*.md, checks them (V15) and resolves each pick to its entry. */
+function loadStacks(entries, vocab, spdxAllowed) {
+  if (!fs.existsSync(STACKS)) return { stacks: [], errors: [] };
+  const files = fs
+    .readdirSync(STACKS)
+    .filter((n) => n.endsWith(".md") && n !== "README.md")
+    .sort()
+    .map((n) => ({ rel: `stacks/${n}`, text: fs.readFileSync(path.join(STACKS, n), "utf8") }));
+  const terms = licenceTerms(vocab, spdxAllowed);
+  const byPath = new Map(entries.map((e) => [e.path, e]));
+  const errors = checkStacks(files, byPath, terms, new Date().toISOString().slice(0, 10));
+  if (errors.length) return { stacks: [], errors };
+  const stacks = files.map(({ rel, text }) => {
+    const parsed = parseStack(text, { file: rel, terms });
+    const picked = parsed.sections.flatMap((s) =>
+      s.picks.map((p) => ({ ...p, section: s.name, entry: byPath.get(pickPath(rel, p.href)) }))
+    );
+    return { ...parsed, rel, picked };
+  });
+  return { stacks, errors };
+}
+
+/** Writes dist/stack/<id>/index.html for every stack. */
+function writeStackPages({ stacks, entries, config, stats, stamp, hasCard, now }) {
+  const errors = [];
+  const written = [];
+  const resolverFor = linkResolvers(entries, config, "../../entry/");
+  for (const stack of stacks) {
+    try {
+      const resolveLink = resolverFor({ path: stack.rel });
+      const leadHtml = renderBlocks(stack.lead, { file: stack.rel, resolveLink, firstLine: stack.leadLine });
+      const sections = stack.sections.map((s) => ({
+        name: s.name,
+        rows: stack.picked
+          .filter((p) => p.section === s.name)
+          .map((p) => ({ need: p.need, entry: p.entry, whyHtml: renderInline(p.why, resolveLink) })),
+      }));
+      const gapsHtml = stack.gaps.map((g) => renderInline(g.text, resolveLink));
+      const html = stackPageHtml({
+        stack,
+        sections,
+        gapsHtml,
+        leadHtml,
+        owed: owes(stack.picked),
+        site: config.site,
+        stamp,
+        total: stats.total,
+        hasCard,
+        now,
+      });
+      const dir = path.join(DIST, "stack", stack.meta.id);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, "index.html"), html);
+      written.push(`stack/${stack.meta.id}/index.html`);
+    } catch (err) {
+      if (err instanceof MarkdownError || err instanceof LinkError) errors.push(err.message);
+      else throw err;
+    }
+  }
+  return { errors, written };
+}
+
+function stackRowsHtml(stacks) {
+  return stacks
+    .map((s) => `<li><a href="stack/${esc(s.meta.id)}/">${esc(s.meta.title)}<span>${esc(s.meta.task)}</span></a></li>`)
+    .join("\n");
 }
 
 /** Writes dist/entry/<id>/index.html for every entry. */
-function writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now }) {
+function writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now, usedIn = new Map() }) {
   const errors = [];
   const written = [];
   const resolverFor = linkResolvers(entries, config);
@@ -428,6 +502,7 @@ function writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now }
         total: stats.total,
         hasCard,
         now,
+        stacks: usedIn.get(entry.id) || [],
       });
       const dir = path.join(DIST, "entry", entry.id);
       fs.mkdirSync(dir, { recursive: true });
@@ -456,6 +531,17 @@ function main() {
   const config = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
   const vocab = JSON.parse(fs.readFileSync(VOCAB_PATH, "utf8"));
   const { entries, errors, bodies } = loadEntries(vocab);
+  const spdxAllowed = JSON.parse(fs.readFileSync(SPDX_ALLOWED_PATH, "utf8"));
+  const { stacks, errors: stackErrors } = loadStacks(entries, vocab, spdxAllowed);
+  // Entry id => the stacks that pick it, for "Used in" on entry pages.
+  const usedIn = new Map();
+  for (const s of stacks) {
+    for (const p of s.picked) {
+      const list = usedIn.get(p.entry.id) || [];
+      if (!list.some((x) => x.id === s.meta.id)) list.push({ id: s.meta.id, title: s.meta.title });
+      usedIn.set(p.entry.id, list);
+    }
+  }
 
   if (errors.length) {
     console.error("Build warnings:");
@@ -514,6 +600,7 @@ function main() {
   const visible = entries.filter((e) => e.status !== "deprecated");
   const substitutions = {
     HEAD_META: headMetaHtml(config.site, stats, payload.generatedAt, hasCard),
+    STACK_ROWS: stackRowsHtml(stacks),
     STARTER_ROWS: starterRowsHtml(featured),
     ENTRY_ROWS: groupedRowsHtml(visible, config.categories, repoUrl, now),
     CATEGORY_CHIPS: categoryChipsHtml(visible, config.categories),
@@ -533,12 +620,18 @@ function main() {
   }
   fs.writeFileSync(indexPath, html);
 
-  fs.writeFileSync(path.join(DIST, "sitemap.xml"), sitemapXml(config.site, visible));
+  fs.writeFileSync(path.join(DIST, "sitemap.xml"), sitemapXml(config.site, visible, stacks));
   fs.writeFileSync(path.join(DIST, "robots.txt"), robotsTxt(config.site));
   fs.writeFileSync(path.join(DIST, "404.html"), notFoundHtml(config.site));
 
-  const pages = writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now });
-  const pageErrors = [...pages.errors, ...checkPages(["index.html", ...pages.written])];
+  const pages = writeEntryPages({ entries, bodies, config, stats, stamp, hasCard, now, usedIn });
+  const stackPages = writeStackPages({ stacks, entries, config, stats, stamp, hasCard, now });
+  const pageErrors = [
+    ...stackErrors,
+    ...pages.errors,
+    ...stackPages.errors,
+    ...checkPages(["index.html", ...pages.written, ...stackPages.written]),
+  ];
   if (pageErrors.length) {
     console.error(`Page build failed (${pageErrors.length}):`);
     for (const e of pageErrors.slice(0, 50)) console.error(`  - ${e}`);
@@ -547,7 +640,7 @@ function main() {
 
   // After the page gate: every body link has resolved by now, so the llms
   // files cannot hit a link error of their own.
-  fs.writeFileSync(path.join(DIST, "llms.txt"), llmsTxt({ entries, site: config.site, categories: config.categories }));
+  fs.writeFileSync(path.join(DIST, "llms.txt"), llmsTxt({ entries, site: config.site, categories: config.categories, stacks }));
   fs.writeFileSync(
     path.join(DIST, "llms-full.txt"),
     llmsFullTxt({
@@ -556,14 +649,15 @@ function main() {
       categories: config.categories,
       bodies,
       resolverFor: linkResolvers(entries, config),
+      stacks,
     })
   );
 
   console.log(
     `Built ${entries.length} entries → site/dist (${stats.active} active, ${stats.commercialOk} commercial-ok, ${stats.commercialVaries} per-file)`
   );
   console.log(
-    `Prerendered ${visible.length} entry rows into index.html; wrote ${pages.written.length} entry pages, sitemap.xml, robots.txt, 404.html`
+    `Prerendered ${visible.length} entry rows into index.html; wrote ${pages.written.length} entry pages, ${stackPages.written.length} stack pages, sitemap.xml, robots.txt, 404.html`
   );
   if (errors.length) process.exitCode = 0; // soft-fail missing fields as warnings
 }

site/lib/entry-page.mjs

@@ -55,7 +55,7 @@ function credit(entry) {
   return { value: "Unclear: read the Notes", script: false, block: "" };
 }
 
-export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml, prev, next, site, categoryLabel, stamp, total, hasCard, now }) {
+export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml, prev, next, site, categoryLabel, stamp, total, hasCard, now, stacks = [] }) {
   const repo = site.repo;
   const url = entryPageUrl(site, entry.id);
   const title = `${entry.name} (${entry.license}) | ${site.title}`;
@@ -99,6 +99,9 @@ export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml,
         ${next ? `<a class="btn-ghost" href="../${esc(next.id)}/" rel="next">${esc(next.name)} <span aria-hidden="true">&rarr;</span></a>` : "<span></span>"}
       </nav>`
       : "";
+  const usedIn = stacks.length
+    ? `<p class="used-in">Used in: ${stacks.map((s) => `<a href="../../stack/${esc(s.id)}/">${esc(s.title)}</a>`).join(", ")}</p>`
+    : "";
   return `<!DOCTYPE html>
 <html lang="en">
   <head>
@@ -129,6 +132,7 @@ export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml,
       <a class="brand" href="../../">Free Game Dev Assets</a>
       <nav class="topnav" aria-label="Primary">
         <a href="../../#catalog">Catalog</a>
+        <a href="../../#stacks">Stacks</a>
         <a href="../../#starters">Starters</a>
         <a href="../../#guides">Guides</a>
         <a href="${esc(repo)}" rel="noopener noreferrer">GitHub</a>
@@ -155,6 +159,7 @@ export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml,
         <a class="btn-ghost" href="${esc(`${repo}/blob/main/${entry.path}`)}" rel="noopener noreferrer">View the file on GitHub</a>
         <a class="btn-ghost" href="${esc(issue)}" rel="noopener noreferrer">Report a problem with this entry</a>
       </p>
+      ${usedIn}
       <div class="entry-content">${restHtml}</div>
       ${pager}
     </main>

site/lib/lib.test.mjs

@@ -307,6 +307,18 @@ lacks("stack json-ld cannot close its script", sld, "</script");
 eq("stack json-ld lists the picks", JSON.parse(sld).itemListElement[0].url, "https://x.test/s/entry/a/");
 eq("stack json-ld name survives", stackJsonLd(stackMeta, [{ rows: [] }], site).name, 'Make a "thing" </script>');
 
+/* stacks: links in --------------------------------------------------------- */
+const pageWithStacks = entryPageHtml({ entry: base, leadHtml: "<p>Lead</p>", restHtml: "", deprecatedReasonHtml: null, prev: null, next: null, site, categoryLabel: "2D", stamp: "2026-09-24", total: 319, hasCard: true, now: Date.parse("2026-09-24T00:00:00Z"), stacks: [{ id: "s1", title: "Make <X>" }] });
+has("used in links the stack", pageWithStacks, 'Used in: <a href="../../stack/s1/">Make &lt;X&gt;</a>');
+lacks("no used in without stacks", p, "Used in");
+const llmsStacks = [{ meta: { id: "s1", title: "Make X", task: "A task.", walked: "2026-09-01" }, picked: [{ need: "Tiles", entry: llmsEntries[0] }] }];
+const lts = llmsTxt({ entries: llmsEntries, site, categories: cats, stacks: llmsStacks });
+has("llms lists stacks", lts, "## Starter stacks\n\n- [Make X](https://x.test/s/stack/s1/): A task.");
+lacks("llms without stacks has no stacks section", lt, "Starter stacks");
+const lfs = llmsFullTxt({ entries: llmsEntries, site, categories: cats, bodies: new Map(), stacks: llmsStacks });
+has("full lists each pick", lfs, "- Tiles: Alpha (https://x.test/s/entry/a1/); CC0; commercial OK; no credit required; active");
+has("full lists credits", lfs, "Credits to ship: none");
+
 /* report (keep last) ------------------------------------------------------ */
 if (failures.length) {
   console.error(`lib.test failed (${failures.length}):`);

site/lib/llms.mjs

@@ -1,6 +1,7 @@
 /** Plain-text indexes of the catalog for AI assistants (llmstxt.org format). */
 import { sectionMarkdown, splitEntryBody } from "./markdown.mjs";
-import { commercialLabel, entryPageUrl } from "./shared.mjs";
+import { commercialLabel, entryPageUrl, stackPageUrl } from "./shared.mjs";
+import { owes } from "./stacks.mjs";
 
 /** The first paragraph of the body before its first `##`, lines joined. */
 function leadParagraph(body) {
@@ -46,17 +47,31 @@ function groups(entries, categories) {
     .filter((g) => g.items.length);
 }
 
-export function llmsTxt({ entries, site, categories }) {
+export function llmsTxt({ entries, site, categories, stacks = [] }) {
   const out = [header(site)];
+  if (stacks.length) {
+    out.push(`\n## Starter stacks\n`);
+    for (const s of stacks) out.push(`- [${s.meta.title}](${stackPageUrl(site, s.meta.id)}): ${s.meta.task}`);
+  }
   for (const g of groups(entries, categories)) {
     out.push(`\n## ${g.label}\n`);
     for (const e of g.items) out.push(`- [${e.name}](${entryPageUrl(site, e.id)}): ${facts(e)}`);
   }
   return `${out.join("\n")}\n`;
 }
 
-export function llmsFullTxt({ entries, site, categories, bodies, resolverFor }) {
+export function llmsFullTxt({ entries, site, categories, bodies, resolverFor, stacks = [] }) {
   const out = [header(site)];
+  if (stacks.length) {
+    out.push(`\n## Starter stacks\n`);
+    for (const s of stacks) {
+      const credits = owes(s.picked).credits.map((c) => c.entry.name);
+      const picks = s.picked.map((p) => `- ${p.need}: ${p.entry.name} (${entryPageUrl(site, p.entry.id)}); ${facts(p.entry)}`);
+      out.push(
+        `### ${s.meta.title}\n\nPage: ${stackPageUrl(site, s.meta.id)}\nTask: ${s.meta.task}\nWalked: ${s.meta.walked}\n\n${picks.join("\n")}\n\nCredits to ship: ${credits.length ? credits.join(", ") : "none"}\n`
+      );
+    }
+  }
   for (const g of groups(entries, categories)) {
     out.push(`\n## ${g.label}\n`);
     for (const e of g.items) {

site/public/index.html

@@ -25,6 +25,7 @@
       <a class="brand" href="#top">Free Game Dev Assets</a>
       <nav class="topnav" aria-label="Primary">
         <a href="#catalog">Catalog</a>
+        <a href="#stacks">Stacks</a>
         <a href="#starters">Starters</a>
         <a href="#guides">Guides</a>
         <a id="repo-link" href="https://github.com/TMHSDigital/Free-Game-Dev-Assets" rel="noopener noreferrer">GitHub</a>
@@ -44,6 +45,14 @@ <h1 id="hero-title">Free Game Dev Assets</h1>
         </p>
       </section>
 
+      <section class="section" id="stacks" aria-labelledby="stacks-title">
+        <div class="section-head">
+          <h2 id="stacks-title">Starter stacks</h2>
+          <p>One pick per need for a kind of game, and what the whole set owes.</p>
+        </div>
+        <ul class="stack-list"><!--STACK_ROWS--></ul>
+      </section>
+
       <section class="section" id="starters" aria-labelledby="starters-title">
         <div class="section-head">
           <h2 id="starters-title">Safe starting points</h2>