Reference · discovery

Feeds & well-known endpoints

Every machine-readable URL on the site — feeds, sitemap, manifest, robots.txt, security.txt, humans.txt, and the JSON-LD records inside each page's head.

~3 min read · 776 words

A labor of love by Hunter Davis. Most of the site is HTML for humans; this page lists everything that isn’t. Each URL has a stable path, a documented purpose, and an auto-discovery entry in _includes/head.html so crawlers and feed readers can find it without scraping the body.

If you paid for this, you were cheated. Open source and free.

On this page

Feeds

Four feeds — Atom + JSON for two collections. Both formats carry the same set of items per collection; pick the one your reader supports. The devlog feed embeds full post bodies inside <content>; the lab feed is headlines + summaries only (a Jekyll constraint — iterating site.html_pages from another page’s render doesn’t guarantee each entry’s .content has been processed yet, so the feed publishes the description instead of risking partial bodies).

Path Format MIME Body Auto-discovery <link rel="alternate"> title
/devlog/feed.xml Atom 1.0 application/atom+xml full Devlog (Atom)
/devlog/feed.json JSON Feed 1.1 application/feed+json full Devlog (JSON Feed)
/lab/feed.xml Atom 1.0 application/atom+xml summary only Lab (Atom)
/lab/feed.json JSON Feed 1.1 application/feed+json summary only Lab (JSON Feed)

All four feeds emit absolute URLs (built from site.url + site.canonical_baseurl) so the build’s path-portable --baseurl "" override doesn’t strip the project prefix from the entry links.

Discovery

The endpoints that tell crawlers what to crawl and where to find the rest.

/sitemap.xml
Hand-rolled XML sitemap — no jekyll-sitemap plugin (its default output would emit URLs without the /johnny-castaway-ps1 prefix because the build runs with --baseurl ""). Pages opt out by setting sitemap: false in front matter; the four feeds, the 404, robots.txt, security.txt, humans.txt, and the manifest all do. Uses site.canonical_baseurl directly so absolute URLs survive.
/robots.txt
Permissive (User-agent: * / Allow: /). The only directive that matters is the absolute Sitemap: line pointing at the sitemap above. Auto-generated wrapper pages under /source/, /resources/, and /archaeology/regtest-references/cases/ opt out of indexing via a <meta name="robots" content="noindex"> tag in their head — not a Disallow: block here — so the rule stays consistent across crawlers that handle the two differently.
/.well-known/security.txt
RFC 9116 responsible-disclosure pointer. Two Contact: lines — GitHub Issues for public reports, GitHub Security Advisories for private. The Expires: field forward-dates one year on every rebuild via Liquid date math (site.time + 31536000), coarsened to T00:00:00Z so same-day rebuilds don’t churn the file.

Identity

The endpoints that say who wrote this and what it is.

/humans.txt
humanstxt.org format. Voice mirrors the in-game drawCredits screen and the /credits/ page. Dynamic fields (release tag, build day, scenes validated) rendered from Jekyll. Auto-discoverable via <link rel="author" type="text/plain">.
/site.webmanifest
W3C web app manifest. The site is not a service-worker-backed PWA — display: browser keeps each page in normal Chrome — but the manifest gives mobile browsers a canonical source for “Install” / “Add to Home Screen” / app-switcher identity. Theme and background colors mirror the light-scheme CSS palette. Three icon entries (16/32/180) referencing the same branding assets the favicon and apple-touch-icon <link> tags use. Auto-discoverable via <link rel="manifest">.

Structured data (in every page’s <head>)

Every page emits one or more Schema.org JSON-LD records inside its head. Multiple <script type="application/ld+json"> blocks are valid — crawlers merge them — so each record is conditional on the page kind:

Record type Emitted on
WebSite every page
SoftwareApplication the home page only (GameApplication · Screensaver)
BreadcrumbList every page except the home page
BlogPosting devlog posts (layout: post + date)
Article lab essays (/lab/<slug>/ with date, excludes the index)
CreativeWork per-scene pages (layout: scene)
FAQPage /faq/
Dataset /perf/ — the 126-row scene/tide matrix
ItemList /scenes/ — all 63 scenes as ListItems
HowTo /play/ — the DuckStation 4-step quickstart
SoftwareSourceCode /play/ — code repository + language

The emission logic for the cross-page records lives in _includes/json-ld.html; the page-specific records (FAQPage, Dataset, ItemList, HowTo, SoftwareSourceCode) are inline at the top of their respective source pages because each iterates page-local content the cross-page emitter doesn’t see.

Source on GitHub

  • Lab: the site itself, as a small program — the magazine treatment of the Jekyll deployment: canonical_baseurl, no-plugin feeds, the redirect override, the build-stamp coarsening pattern that the security.txt Expires field also uses.
  • Credits — the human-readable counterpart to humans.txt.
  • Legal — the security.txt Policy: target.
  • Glossary — the rest of the site’s vocabulary.