com.gregkilmer.www/docs/site.md

The site

services/site (@gk/site) is the public GregKilmer.com. It is an Astro app rendered on request by the Node adapter. It reads only the content service, with a reader token, and only published notes.

How a page gets its data

---
import PageShell from "@gk/ui/components/PageShell.astro";
import { site } from "../lib/page.ts";
const s = await site();            // the SiteIndex: every published note in memory
const games = s.all("board-game"); // typed: games[0].data.bggId is a number
---

src/lib/content.ts loads every published note from the content service and refreshes in the background every 30 seconds (CONTENT_REFRESH_SECONDS). If the service is down, the last good copy keeps serving.

src/lib/site.ts (SiteIndex) answers everything a page asks:

Method	Gives
all(type), one(type), bySlug(type, slug), byName(name or [[link]])	Notes.
href(note)	The address that shows a note (see the URL map below).
link("[[Name]]")	{ title, href, note }; href is null when the note is not published, so render plain text.
backlinks(note, { type })	Notes linking to it, newest first. Links to a make count for its craft, a deck for its game, a campaign for its system.
linksFrom(note)	Notes it links to.
posts({ topic }), caseStudies()	Blog posts and case studies, newest first.
statuses(), statusFor(note)	The status log (newest per subject, pinned first) and a note's current status.
kind(label)	A status kind's brand icon and page.
pageText(path)	The Page text note for an address: lede, body, quick facts.
settings()	Site settings: name, tagline, availability, socials.
render(markdown)	Safe HTML with wikilinks resolved.
redirect(type, slug)	Where an old slug now lives; answer it with a 301.

mediaSrc(value) turns an image field into a /media/<file> address, which passes vault images through from the content service. formatDate("2026-10-11") gives "Oct 11, 2026".

URL map

Address	Shows
/	Landing
/about	About me
/resume, /resume.pdf	Resume and its PDF
/work, /work/<slug>	Case studies and each study
/inquiries, /inquiries/sent	Inquiry form and its confirmation
/library, /library/shelf	The Library and The Shelf; items are anchors #<slug>
/workshop, /workshop/<craft>	Workshop and each craft; makes are anchors on their craft
/tabletop	Systems, campaigns, card games and decks as anchors
/now	Every status; each is an anchor
/blog, /blog/topic/<topic>, /blog/<slug>, /rss.xml	Blog, topics, posts, feed
/store, /store/<line>, /store/order, /store/order/sent	Store, product lines, order form and its confirmation
anything else	404, Off the star chart

Rules for pages

• Build from the components in @gk/ui (see components.md) and the gk-* classes. Every page uses PageShell with its family (edge seal) and current (nav entry); its hero goes in the hero slot.
• All dark. Panels are Midnight with a gold frame, not Starlight.
• Never invent facts or numbers. Where a note has no value, leave the element out, or show [PLACEHOLDER] where the design needs text Greg has not written yet.
• No phone numbers. Email addresses stay as they are in the notes.
• Lists of posts are fixed-height rows, not stretching cards.
• Small client scripts (filters, tabs) are fine; the page must read correctly without them.

Running it locally

# the content service, against a copy of the Site folder
SITE_DIR=… DATA_DIR=… CONTENT_TOKENS="reader:<24+ chars>" npm run content
# the site
CONTENT_URL=http://localhost:4310 CONTENT_TOKEN=<reader token> npm run site   # http://localhost:4330

For a local preview of drafts, set CONTENT_INCLUDE_DRAFTS=true with an editor or admin token. Never set it where the public can reach the site.

The resume PDF

/resume.pdf is drawn with pdfkit from the same resumeData() as /resume (src/lib/resume.ts), so the two never disagree. Each page is laid over the personal Greg Kilmer letterhead, the version without Patiun LLC (src/assets/letterhead, a copy of Greg-Kilmer-Personal-Letterhead.pdf from the branding letterheads; re-copy it when that letterhead changes) with pdf-lib, which keeps both as vectors. It reads top to bottom so applicant tracking systems take it in order, aims for one page (roles marked earlier print as a short list; skills share a row with education and projects), and when a one-page resume ends well above the footer it is laid out again with wider gaps (up to twice as wide) so the page reads as full. It uses the brand TTFs in src/assets/pdf-fonts, and is rebuilt only when the notes behind it change. The highlights row and Selected projects come from the /resume Page text note's stats and projects. Greg's Resume Interview answers live in tools/migrate/src/seed.ts.

Where each page lives

Page	File	Helpers
Landing, About, Now	pages/index.astro, about.astro, now.astro	lib/home.ts, components/home
Resume and PDF	pages/resume.astro, resume.pdf.ts	lib/resume.ts, lib/resume-pdf.ts
Work, case studies	pages/work/	lib/work.ts, components/work, components/blog/PostLayout
Inquiries, sent, 404	pages/inquiries/, 404.astro	lib/work.ts
Library, Shelf	pages/library/	lib/library.ts, components/library
Workshop, crafts, Tabletop	pages/workshop/, tabletop.astro	lib/world.ts, components/world
Blog, topics, posts, RSS	pages/blog/, rss.xml.ts	lib/blog.ts, components/blog
Store, lines, order	pages/store/	lib/store.ts, components/store

Filters on world pages

• Shelf: How it plays, Players, Play time, Owned, Want to play, Favorites and Has a blog post, plus four sorts. Players and Play time read the BoardGameGeek sync and only appear once some game has those values. With no filter narrowing the list, the first 12 games show and "Show all" opens the rest.
• Craft pages: when a craft's makes carry two or more tags (Dice, Rings, and so on; sword rack does not count), pills above the grid filter them. Makes without a tag fall under Other.

Forms

The Inquiries form posts to POST /api/inquiries and the order form to POST /api/orders (src/pages/api/). Both are plain multipart posts that answer with a 303 redirect, so they work without JavaScript. The rules are plain functions in src/lib/forms.ts (tested in services/site/test); the network calls are in src/lib/forms-server.ts.

1. A filled honeypot field (leave_blank) gets the confirmation page and nothing else.
2. The answers are checked. Inquiries take only the chosen type's job_*, freelance_* or patiun_* fields; others are ignored.
3. A per-address rate limit, then Cloudflare Turnstile when TURNSTILE_SECRET_KEY is set (a missing or bad token, or Cloudflare being unreachable, turns the post down).
4. Orders only: the line is checked against the live store notes, fetched from the content service then and there. An order goes through only for a line sold here, in a category with ordersOpen: true, with an open slot (made to order) or stock, and with in-stock options. Otherwise it is turned down, whatever was posted.
5. The copy is saved through the content service with CONTENT_INTAKE_TOKEN, then emailed (SMTP via nodemailer) to CONTACT_TO or ORDER_TO, and the email's result is recorded on the copy. A failed email still shows the visitor the confirmation; the admin Inbox flags it. If saving fails the email is still tried; only when neither works does the form show an error.
6. Success redirects to /inquiries/sent (cookie gk-inquiry) or /store/order/sent (cookie gk-order): URL-encoded JSON, httpOnly, SameSite Lax, ten minutes, secure in production. A turned-down post goes back to the form with ?error=<code> and a gk-inquiry-draft or gk-order-draft cookie holding the reason, the marked fields and the answers (an attachment has to be added again).

Settings are in services/site/.env.example: CONTENT_INTAKE_TOKEN, PUBLIC_TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY, SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM, SMTP_ALLOW_SELFSIGNED, CONTACT_TO, ORDER_TO, CONTACT_RATE_LIMIT, CONTACT_RATE_WINDOW_MIN, ORDER_RATE_LIMIT, ORDER_RATE_WINDOW_MIN, FORM_MAX_ATTACHMENT_MB. The Turnstile widget needs JavaScript; with the secret set, a visitor without it cannot send a form.