- TypeScript 77%
- Astro 17%
- CSS 6%
- Shell <1%
- Docker <1%
scarnecchia.net #
Personal site for Scarnecchia: writing, projects, design, photography, and CV.
Built with Astro 5 as a fully static site. There is no CMS and no database: all content lives as AT Protocol records on a PDS, fetched at build time via public XRPC endpoints and validated with Zod schemas. Publishing content means writing records to the PDS; the site picks them up on the next build.
drafts/*.md ──publish:post──▶ PDS records ──npm run build──▶ dist/ (static HTML)
Grain app ───────────────────▶ (curation record selects what appears)
| Content | Record type | Route | How it gets there |
|---|---|---|---|
| Essays / notes | site.standard.document (path /writing/*) |
/writing/<slug> |
npm run publish:post |
| Project case studies | site.standard.document (path /projects/*) |
/projects/<slug> |
npm run publish:post with section: projects |
| Photography | social.grain.gallery + photos |
/photography, /photography/<rkey> |
Galleries made in the Grain app, selected via npm run publish:curation photo add |
| Design portfolio | systems.numina.site.curation entries |
/design |
npm run publish:curation design add |
| CV | id.sifa.profile.* records |
/work |
Edited directly on the PDS |
Note the naming: the nav label Work is the CV at /work; the portfolio is
Projects at /projects. Records published before the projects section
existed may still carry /work/* record paths; they render at /projects/*
(mapped by src/lib/site-path.ts, with redirects for old URLs).
Setup #
npm install
cp .env.example .env # then fill in the app password
.env is only needed for publishing (writes). Reads are public: npm run dev
and npm run build need no credentials.
| Variable | Purpose |
|---|---|
PDS_URL |
PDS host, e.g. https://shiitake.us-east.host.bsky.network |
ATP_IDENTIFIER |
DID (or handle) of the account |
ATP_APP_PASSWORD |
App password (create at bsky.app → Settings → App Passwords) |
One-time bootstrap (already done for the live site): npm run publish:init
creates the publication record, an empty curation record, and publishes the
curation lexicon schema.
Writing and publishing a post #
-
Create a Markdown file in
drafts/with frontmatter:--- title: "On Field Notes" description: "Optional one-line summary, used in listings and meta tags." tags: ["note"] section: writing cover: ./images/on-field-notes-cover.jpg date: 2026-07-18 --- Body in standard Markdown. Code fences get Shiki highlighting.Field Required Notes titleyes slugno [a-z0-9-]+only. Omit for rkey addressing — the minted TID record key becomes the URL slug (/writing/<rkey>, like photography's/photography/<rkey>); author one only when you want a readable URL. URLs are derived from the record'spath, whose final segment is the slug (or the rkey). Changing the slug on a later publish creates a new record/URL.rkeyno 13-char TID record key. Written back into the draft automatically after the first publish of a slug-less draft; from then on it is the update handle for post/status/delete. Hand-editing it to a rkey with no published record creates a record at that rkey.descriptionno Listing and OG description tagsno case-studychanges the row CTA on/projectssectionno writing(default) orprojects.projectsrenders under/projects/sourceno Absolute URL to the project's source code, e.g. https://github.com/you/repo. Rendered as a Source link on/projects; omit entirely for none. Relative or malformed URLs are rejected at publish time.coverno Path to an image, relative to the draft file. See Images below. dateno Sets publishedAton first publish. Omit to use publish time.The record's
pathfield stays populated either way — standard.site's verification flow constructs document URLs fromsite+path, and the site derives its routes frompath(src/lib/site-path.ts). Existing posts keep their authored URLs; migrating them to rkey addressing is out of scope. -
Publish:
npm run publish:post drafts/on-field-notes.mdPublishing is an idempotent upsert: keyed on
rkeywhen the draft carries one (added automatically after a slug-less first publish — the CLI printsrkey saved to <draft>), otherwise resolved by the record'spathfromslug. Run it again after edits and the record is updated in place (publishedAtis preserved,updatedAtis set; a rkey-addressed update keeps the existing record'spathverbatim, so a legacy URL never moves). Multiple files can be passed at once.Two pitfalls to know: duplicating a draft to start a new post carries its
rkey(andslug) with it — clear both before publishing, or the copy updates the original's record instead of creating a new one (the CLI names the record it updated:updated existing record "…"). And removingslugfrom a draft that was published via the legacy flow mints a fresh rkey and creates a new record/URL — delete the old record if you de-slug an existing post. -
Check status of drafts against the PDS:
npm run publish:status drafts/*.mdReports
new,current, orchangedper file. -
Rebuild the site (see Deploying) — content is fetched at build time, so a published record is invisible until the next build.
Deleting a post #
npm run delete:post <rkey> # by record key (the TID written into the draft)
npm run delete:post <slug> # by slug (path-keyed posts)
npm run delete:post drafts/post.md # by draft file (rkey or slug read from frontmatter)
Deletes the site.standard.document record from the PDS. Resolution is
rkey-first (exact record-key match), with the slug/path match as fallback —
so a rkey works even when the record carries a preserved legacy path.
Multiple rkeys, slugs, or files can be passed at once. Two things to know:
- A post pinned in the curation record is refused (a dangling pin fails the
next build) — run
npm run publish:curation -- unpin <at-uri>first. - The draft file is untouched; delete or keep it as you like. Blobs the record referenced become unreferenced and are eligible for PDS garbage collection.
As with publishing, the live site changes on the next rebuild.
Images #
Cover images #
Set cover: in frontmatter to a path relative to the draft file. On publish,
the CLI validates the file and uploads it as a blob on the record.
- Formats: JPEG, PNG, or WebP
- Max size: 1 MB (
MAX_COVER_BYTES) — resize/compress before publishing - At build time the blob is downloaded and cached to
src/assets/pds/(gitignored) and rendered through Astro's image pipeline - Covers appear on project cards and OG tags. Cards without a cover get a branded fallback, so a cover is optional.
The design portfolio uses the same upload path via
npm run publish:curation -- design add --image path/to/file.png ....
Note the -- in every curation example: npm swallows --flags that come
before it (with only a warning), so without the separator the flag never
reaches the CLI and the record is written without that field.
Inline images in a post body #
Reference images with normal Markdown syntax and a path relative to the draft file, exactly like the cover:

On publish:post, the CLI finds every local image reference in the body,
validates it (JPEG/PNG/WebP, ≤ 5 MB), uploads it as a blob, and rewrites the
reference in the published record to the blob's public getBlob URL. The
uploaded blobs are listed in an embeds field on the record, which is what
keeps the PDS from garbage-collecting them.
At build time the site downloads each embedded blob into public/pds/
(gitignored) and rewrites the markdown to the self-hosted /pds/<cid>.<ext>
copy — the live site never hot-links the PDS, and fixture builds stay
offline. Rules and edge cases:
- Alt text is preserved; always write it.
- Image references inside code fences or inline code are examples, not embeds — they are left untouched.
- Remote URLs (
https://…) are also left untouched; use them for images hosted elsewhere (e.g. Flickr). - Re-publishing re-uploads the bytes; identical bytes produce the same CID, so unchanged images are a no-op on the PDS.
publish:statusignores image URL rewrites when diffing, so a published post still readscurrent.
How images move through the protocol #
Blobs are not records and have no lexicon of their own — they are
CID-addressed bytes in the repo's blob store, moved by core com.atproto.*
procedures. The only content lexicon involved is site.standard.document:
- Upload —
com.atproto.repo.uploadBlob(authenticated) sends the bytes and returns a blob ref:$type: "blob", CID, MIME type, size. - Reference — the blob ref is written into the document record via
com.atproto.repo.putRecord:coverImagefor covers,embedsfor inline images. This step matters: the PDS only retains blobs referenced by some record. An uploaded blob nothing points at is eligible for garbage collection. - Read —
com.atproto.sync.getBlob?did=…&cid=…serves the bytes publicly, no auth. The build fetches through this endpoint (and caches the result), and it is the URL form stored in published markdown.
Photography #
Photography is published as galleries. The photos, EXIF sidecars, gallery
records, and gallery membership (social.grain.photo, social.grain.gallery,
social.grain.gallery.item) are all created in the
Grain app — this repo never writes them. The curation
record then selects which galleries appear on /photography and in what
order. Curation is galleries-only: every subject must be a
social.grain.gallery AT-URI. An individual photo URI fails the build with
"curation photography subject is not a gallery".
To publish a gallery end to end:
-
In Grain, upload the photos and collect them into a gallery with a title and (optionally) a description and location. The description becomes the statement in the gallery page header; the gallery's first photo is the cover on the
/photographyindex. -
Find the gallery's AT-URI:
at://<did>/social.grain.gallery/<rkey>. Any atproto record browser (e.g. pdsls.dev) can list the repo'ssocial.grain.galleryrecords; already-curated URIs show innpm run publish:curation show. -
Add it to the curation record (the subcommand is named
photofor historical reasons — the subject is a gallery URI):npm run publish:curation -- photo add <gallery-at-uri> [--position n] [--feature] [--flickr url] npm run publish:curation -- photo move <gallery-at-uri> <position> npm run publish:curation -- photo remove <gallery-at-uri>--featuremakes the gallery card span two columns on the index.--flickradds a "View on Flickr" outlink on the gallery page. Omitting--positionprepends: the newest curated gallery leads the page. -
Rebuild and deploy (see Deploying).
Gallery detail pages render at /photography/<rkey>/ — all photos in
gallery order with EXIF captions, plus title/description/location from the
gallery record. Two build-time invariants to know: a curated gallery must
contain at least one photo, and the gallery record must still exist on the
repo — deleting a gallery in Grain without removing it from curation breaks
the next build.
Design portfolio #
Design pieces live only in the curation record (no document record):
npm run publish:curation -- design add \
--title "Poster Series" --year 2025 --medium "Print" \
--image path/to/image.png [--description "..."] [--position n]
npm run publish:curation -- design remove "Poster Series"
--title, --year, --medium, and --image are required. The image is
uploaded as a blob on the curation record: JPEG/PNG/WebP, ≤ 2 MB. (This cap
comes from our own curation lexicon in lexicons/; raising it again means
editing the lexicon's maxSize and re-running npm run publish:init to
republish the schema. Post covers are capped at 1 MB separately — that
limit belongs to the upstream site.standard.document lexicon.)
Unlike photos there is no design move — to reorder, design remove the
piece and re-add it with --position. Removal is keyed on the exact title.
Two rendering behaviours on /design worth knowing (src/pages/design.astro):
- Frames cycle through fixed aspect ratios (3/2, 4/5) for visual variety;
images are cropped to fit (
object-fit: cover). - Pieces whose
--mediumcontains "illustration" or "type", or whose image is a PNG, render uncropped (object-fit: contain) instead — use one of those mediums for posters or layouts where cropping would cut content.
Pinned items #
The home page respects pinned document ordering:
npm run publish:curation -- pin <at-uri>
npm run publish:curation -- unpin <at-uri>
npm run publish:curation -- show # dump the full curation record
CV #
/work renders from id.sifa.profile.* records (self, position,
education, publication, project, skill, presentation,
volunteering, ...). There is no publisher command for these; edit the
records directly on the PDS with an atproto record tool. Schemas are in
src/schemas/sifa.ts. The page doubles as a print resume (print stylesheet
hides nav/footer; keep it to 1–2 pages).
Local development #
npm run dev # dev server against the live PDS
npm run build # production build → dist/
npm run preview # serve dist/ locally
npm run build:fixtures # deterministic build from recorded fixtures (no network)
npm run preview:fixtures # preview a fixture-backed build
npm run astro -- <cmd> # any other Astro CLI command (check, sync, ...)
Fixture mode (ASTRO_TEST_FIXTURES=1) swaps the XRPC client for one backed by
tests/fixtures/recorded/*.json and makes zero network requests. After
publishing content that tests depend on, refresh fixtures with
node tools/record-fixtures.mjs and review the diff before committing.
Testing #
npm test # Vitest unit/integration (includes a full build check)
npm run test:e2e # Playwright E2E + visual regression (builds with fixtures)
npm run test:e2e:ui # Playwright interactive mode
npm run test:e2e:report # open the last HTML report
See docs/CONTRIBUTING_E2E.md for fixture format, baseline policy, and
troubleshooting. Visual baselines are platform-suffixed; never update a
baseline without reviewing it against scarnecchia-design-kit/. If the E2E
web server complains port 4321 is taken, kill the stale preview:
lsof -ti :4321 | xargs kill.
Deploying #
The build output is plain static files — any static file server works. Today, deployment is manual:
npm test && npm run test:e2e # verify
npm run build # fetches live PDS content → dist/
# copy dist/ to the web server
Because content is fetched at build time, every content change needs a rebuild and redeploy — publishing a record alone does not update the live site.
An automated pipeline is planned but not yet implemented (see
docs/implementation-plans/2026-07-18-scarnecchia-site/phase_05.md): the site
will run on the k3s node behind the existing Caddy proxy, with a watcher
consuming Jetstream that triggers a rebuild Job whenever site records change
on the PDS, plus a daily rebuild as a safety net. Once that lands, publishing
a record is the whole deploy.
Repo map #
drafts/ Markdown drafts (source of truth stays on the PDS once published)
lexicons/ Published lexicon schemas (contracts — coordinate changes)
src/pages/ Routes (index, writing, projects, design, photography, work, rss, 404)
src/loaders/ Astro content-layer loaders that fetch PDS records at build
src/schemas/ Zod schemas for every record type
src/lib/ Pure logic: XRPC client, path mapping, EXIF, dates
src/styles/ Design tokens, Vignelli grid, nav, print, sidenotes
tools/publisher/ The publish CLI (post / delete / curation / status / init)
tools/record-fixtures.mjs Refresh recorded PDS fixtures
tests/ Vitest + Playwright suites and fixtures
docs/ E2E contributing guide, implementation plans
scarnecchia-design-kit/ Design reference specimen (read-only)
Deeper conventions, invariants, and agent guidance: AGENTS.md.