Static GitHub Pages UI for this catalog.
site/build.mjs scans every catalog/**/*.md (except README.md / TEMPLATE.md), reads YAML frontmatter, and writes site/dist/data.js + static assets.
| You edit | What updates |
|---|---|
catalog/<category>/<id>.md |
Catalog list, search, filters, counts |
site/config.json → featured |
Safe starting points table (id + need) |
site/config.json → categories / guides |
Labels and guide links |
site/public/* |
Page chrome / design |
site/config.json → categories.<id>.view |
Whether a category previews as cards or as a list |
site/thumbs.json + site/public/thumbs/ |
The preview image on each entry's card, strip and filmstrip (see Thumbnails) |
| An entry's body (Notes, Evidence) | Its page at entry/<id>/ |
stacks/<id>.md |
Its page at stack/<id>/, the homepage Starter stacks list, and "Used in" on each picked entry |
Each deploy also publishes
catalog.csv (one row
per entry, columns in this order: id, name, url, category, license, license_spdx,
commercial, attribution_required, formats, tags, added, verified, status, page,
subcategories, publisher, attribution_string; new columns are appended, never inserted. List
fields are joined with ; , and a cell that starts with =, +, -, @, a tab or a
carriage return gets a leading ' so a spreadsheet does not run it as a formula) and two
Atom feeds:
feed.xml, the 40 newest
entries by added (the day each joined the catalog), and
reverified.xml, the
40 most recently verified entries by verified (the day the licence was last read at the
source). Two feeds, so a re-verification sweep of old entries cannot bury the new ones.
Every deploy publishes the whole catalog as
data.json, for scripts
and tools that want the metadata without scraping the page. The page itself loads
data.js, the same payload assigned to window.__CATALOG__.
- Top-level keys:
generatedAt,version(the calendar tag of the day,vYYYY.MM.DD),site,categories,guides,stacks(id and title),featured,stats(counts:total,active,needsReview,deprecated,listed(total less deprecated: the "N sources" figure),commercialOk,commercialVaries,categories),filters(licenseFamilies, the labels for the Licence filter, andformatGroups, the groups behind the Format filter) andentries. The reader-facing guide to the exports isdocs/data.md. - Each entry carries its frontmatter fields (
id,name,url,category,subcategories,license,license_spdxwhere set,commercial,attribution_required,attribution_stringwhere set (a template marks fields as{name};lib/owes.mjshighlights them and flags them on copy and export),formats,tags,added,verified,status,publisherwhere set, and, only where set,maintenance,engine_lock,ue_versions,limitsand the 2D fieldsgrid_dimensions,camera_perspectiveandhardware_tags), pluspath(the entry's file in this repo),page(the entry's page, relative to the site root),summary(the first paragraph of its body),thumb({ path, width, height, credit? }of the entry's preview image relative to the site root, withcrediton CC-BY images, ornull),licenseFamily(the coarse licence group the site filters on), and two derived sort fields,attributionClassandlicenseRank. - Its shape is
site/data.schema.json(JSON Schema, published asdata.schema.json); the build checks the payload against it withlib/schema-check.mjsand fails on any mismatch, so a renamed or retyped field must change the schema in the same commit. plugin-feed.jsonis a slim copy for editor plugins (lib/plugin-feed.mjs, #277), held tosite/plugin-feed.schema.jsonthe same way; itsformatnumber goes up only on a breaking change (seedocs/data.md).- It is regenerated from
catalog/on every push tomain. Field names are stable; new optional fields may appear. The licence facts are only as current as each entry'sverifieddate: re-check the source before you ship on one.
build.mjs writes entry/<id>/index.html for every entry from its frontmatter and
body, using site/lib/markdown.mjs. The renderer supports exactly what entries use:
# and ## headings, paragraphs, bullet lists (nesting allowed), bold, *italic*,
inline code, links and bare URLs. Underscores are literal. Anything else (tables,
code fences, blockquotes, images, raw HTML, ###, numbered lists) fails the build
with the file and line, as does a relative link to a file that does not exist.
The build also writes llms.txt (one line per entry) and llms-full.txt (with each
entry's Notes) for AI assistants, and checks every generated page before it succeeds.
Tests: node site/lib/lib.test.mjs.
Every entry on the homepage, the category pages, the stack pages and in app.js renders
through one template, site/lib/cards.mjs (entryCardHtml), so the prerender and the
hydrated page cannot drift apart. Cards and List are the same markup under a data-view
attribute; styles.css lays each out. site/config.json sets a category's default view;
site/public/views.js adds the Cards / List toggle to each heading and remembers the
choice per kind of category in localStorage. The homepage shows the first 6 (cards) or
8 (list) entries per category and links "Show all N" to the category page; with app.js
the same link opens the category in place. cards.mjs and shared.mjs are copied into
dist as modules the browser imports, so neither may import from node:.
build.mjs writes category/<id>/index.html for every configured category with a
visible entry: the whole category, both views, no JavaScript needed to see everything
(site/lib/category-page.mjs, toggle from category.js). They are in the sitemap, and
each entry page's breadcrumb links to its category page.
npm run thumbs (site/thumbs.mjs) fetches each eligible entry's og:image from its
url, resizes it to 640 px WebP with ffmpeg (or ImageMagick) and writes
site/public/thumbs/<id>.webp plus a record in site/thumbs.json (source, image URL,
fetch date, content hash, size, licence at fetch). Eligible means status: active and a
licence in the allowlist in site/lib/thumbs.mjs; custom, varies, unknown,
GitHub and Google Fonts pages never qualify; tools and fonts entries qualify only with
a pinned preview: (their page image is a logo or social card the program licence does not
cover); a CC-BY entry needs attribution_string or publisher so the caption can name the
creator; and an image whose bytes three or more entries share is treated as a logo and dropped
(the ids are kept under shared in site/thumbs.json so they are not fetched again until
the record would be refreshed anyway). preview: none opts an entry out;
preview: <https url> pins an image a maintainer has checked. The run is incremental
(a record under 180 days old with the same licence is kept), removes records the gate no
longer allows, and lists failures without failing. validate.mjs fails when the files,
the manifest and the gate disagree (checkThumbManifest). build.mjs attaches thumb
to each entry; entries without one get a typographic tile.
.github/workflows/thumbs.yml runs the script on the first of each month (and on
demand), pushes changes to a thumbs/<month> branch and opens or updates one issue
labelled enhancement with the compare link and the report; the maintainer opens the pull
request from the link so CI runs on it.
Public Sans and IBM Plex Mono are served from site/public/fonts/ (latin WOFF2, OFL,
see the README there). baseHeadHtml in site/lib/shared.mjs emits every page's icon,
font preloads and stylesheet from a root path, and the page checks fail any page that
still references Google Fonts.
build.mjs writes stack/<id>/index.html for each file in stacks/ (the format is in
stacks/README.md). The page's "What this stack owes" panel is computed from the picked
entries: credit lines to ship, licence notices to keep with the files, picks that need no
credit, aggregators to check file by
file, and open questions. A stack never states a licence itself. V15 in checks.mjs
fails a stack whose pick is missing, deprecated or malformed, or whose why sentence
names a licence; validate.mjs and build.mjs both run it.
build.mjs writes a one-line summary under the homepage hero and freshness/index.html
from each entry's verified date, using site/lib/freshness.mjs. The buckets are the
cards' own (fresh up to 180 days, aging to 365, stale after). Deprecated entries are
not counted. pages.yml also runs every Monday at 06:17 UTC so the ages keep moving
when nothing is pushed; GitHub pauses scheduled workflows in a public repository after
60 days without activity, so a long quiet spell needs a manual run from the Actions tab.
build.mjs writes sitemap.xml (home, freshness, category pages, stacks and every non-deprecated entry)
and links it from the homepage with <link rel="sitemap">. The Sitemap: line in
robots.txt is written too, but crawlers only read robots.txt at a host's root, so
under /Free-Game-Dev-Assets/ it is never seen. Submit
https://tmhsdigital.github.io/Free-Game-Dev-Assets/sitemap.xml once in Google Search
Console and Bing Webmaster Tools; that is the step that gets it read.
build.mjs also writes opensearch.xml, an OpenSearch 1.1 description linked from the
homepage with <link rel="search">, so a browser can add the catalog as a search engine;
a search opens the homepage with ?q={searchTerms}.
.github/workflows/links.yml runs site/check-links.mjs every Monday at 07:41 UTC (and
on demand from the Actions tab). It fetches each non-deprecated entry's url and opens,
or updates, one issue labelled correction titled "Link check: N sources need a look",
listing dead links, sources that moved to another domain or GitHub repository, and
entries verified more than a year ago. Sites that refuse the checker (401, 403, 429) are
listed for a manual look but never open the issue on their own. It edits nothing: a
moved source needs its licence re-read before its entry changes. Run it locally with
npm run links.
The live Pages URL changes on every push, so a tool that bundles the catalog (a plugin,
a notebook, a paper) could not pin a version. .github/workflows/release.yml runs on the
first of each month and on demand: it builds, tags vYYYY.MM.DD and creates a GitHub
release with data.json, data.schema.json, plugin-feed.json, catalog.csv, feed.xml,
reverified.xml and llms.txt attached, with the newest section of docs/review-ledger.md as the notes. Fetch a fixed
version by tag from the Releases page; data.json carries the same tag as version.
The workflow passes the tag into the build as CATALOG_VERSION, fails if the built
data.json disagrees, and commits the tag into CITATION.cff (version, date-released)
on main before cutting the release, so the tagged commit cites itself.
.github/workflows/reverify.yml runs site/reverify-batch.mjs on the first of each month
(and on demand). It picks the live entries whose licence was read longest ago, more than
150 days, as many as it takes that no live entry passes 180 days before the next batch
(about a fifth of the catalog a month; batchSizeNeeded in site/lib/reverify.mjs), and opens or updates one issue labelled help wanted and good first issue
titled "Re-verify batch YYYY-MM: N entries due a licence re-read", with a checklist that
names each entry's file, source URL and recorded licence. The selection rule is in
site/lib/reverify.mjs and tested. When nothing is due the month is skipped. Preview it
with node site/reverify-batch.mjs (npm run reverify).
docs/images/readme/og-card.png is a 1200x630 screenshot of this site's first screen.
build.mjs copies it into dist and emits the og:image and twitter:image tags. The
README shows it too, and the hero states the entry count, so it is retaken whenever the
home page can change. .github/workflows/og-card.yml runs after each push to main that
touches catalog/, docs/, site/ or the top-level Markdown: it builds the site, captures
the top 1200x630 of the home page in light mode with no scrollbar (site/og-card.mjs,
headless Chrome), commits the PNG to main only when it differs, and redeploys Pages so the
og:image matches. To retake it by hand: npm run build && npm run og-card (set
CHROME_PATH if Chrome, Chromium or Edge is not found).
npm run check # what CI runs: lint, tests, validate, check-added, build (see CONTRIBUTING.md, "What CI runs")
npm run serve # preview site/dist
npm run links # the link check, printed to the terminal
npm run thumbs # fetch and resize the previews that are due (needs ffmpeg or magick)Script options:
| Command | Options |
|---|---|
node site/build.mjs |
--clean empties site/dist first (otherwise only changed files are written) |
node site/check-links.mjs |
--report <file.md> writes the report to a file; --stale-days <n> (365) flags entries verified longer ago. Set GITHUB_TOKEN: without it the archived-repository checks hit GitHub's anonymous API limit and report "Could not check". It also fetches the licence pages quoted in each entry's Evidence and reports one that no longer loads. Entries on hosts in site/config.json → linkCheck.manualHosts (hosts that refuse scripts every week) are listed as checked by hand with their verified date, not as refused. |
node site/reverify-batch.mjs |
--report <file.md>; --size <n> overrides the computed batch size |
node site/thumbs.mjs |
--only <id,id> limits the run to those entries; --force refetches records that are not due; --limit <n> caps fetches per run; --dry-run writes nothing; --report <file.md> |
node site/serve.mjs |
--port <n>, or the PORT environment variable (3000) |
node site/coverage.mjs (npm run coverage) |
Runs both test suites under Node's built-in V8 coverage and lists, per file, the functions no test calls; --all lists every file. Informational, not part of npm run check |
Deploy: .github/workflows/pages.yml (source = GitHub Actions), which first runs
ci.yml as a reusable workflow.