Page identity: an ID on the first line

Why code pages carry a goatboat ID on their first line, and the alternatives weighed for following pages across folder moves.

Context

Goatboat keeps a row for every code page (source = approute). The site's sync script sends the full list of { path, file } pairs, and goatboat matches them to rows by path.

That broke when a folder moved. Moving src/app/docs/blues to src/app/tests/blues made the old path disappear and a new one appear. The sync flagged the old row as missing and created a new, empty draft at the new path. The old row kept its metadata, the new one had none, and nothing connected them.

The root problem is that a folder in src/app carries no identity. Goatboat mints a row ID on first sync and keeps it in the database, and nothing in the code ever learns it. When both path and file change, there is nothing left to tie the new folder to the old row.

Decision

Each page file starts with a marker on its first line:

tsx
// goatboat: 5cd8149f-3e31-4057-b014-2b8be4c99c4d
  • The sync script reads the first line only, with a regex that ignores the comment syntax around goatboat: <uuid>. It never parses or imports the file.
  • The payload becomes { id?, path, file }.
  • Goatboat matches by id first and by path second. A row matched by ID whose path changed gets its path, parent and file updated, its descendants rewritten, and a redirect left at the old path.
  • Pages without a marker keep working through the path fallback.
  • New pages are scaffolded by a script that writes the folder and a fresh UUID together, and goatboat accepts the client-supplied ID on insert.

Options considered

Match on slug. Rejected. Slugs get edited, deleted and duplicated. It was a heuristic standing in for a key.

Git rename detection (git diff -M). Rejected. Git does not track moves. It stores (path, blob) pairs and infers renames at display time by content similarity.

  • It is a heuristic with a failure mode that is silent: metadata can land on the wrong row.
  • Freshly created pages are often identical boilerplate, so identical blobs give it nothing to pair on.
  • It is stateful (a last-synced SHA) and breaks on history rewrites and squash merges.

A second git history just for moves. Rejected. It only changes where the ID lives. A history of files still relies on inference. A history keyed by UUID filenames works, but then the UUID is doing the job, and a plain mapping file would do the same.

Filesystem metadata (xattrs, inodes). Rejected. Git drops all of it, so a fresh checkout on the Action runner has nothing.

Sidecar file (like Unity .meta). Viable and the strongest alternative. It separates identity from code and has room for more fields later. It costs one extra file per page that must move with it.

Export in page.tsx. Rejected. Next's TypeScript plugin flags unknown exports from page files, and every framework has different rules for what a route module may export.

Central mapping file. Rejected. It must be edited on every move, which is the step that gets forgotten.

Why the first line

A text file has no header. Byte 0 is the first character of the text. The nearest thing to a header is a comment on line 1, the same idea as "use client" or a shebang: inert to the language, readable by tooling.

  • It travels with the file through mv, so it cannot be separated from the page.
  • It is readable with one cheap read and no parsing.
  • It works in any file type, with a different comment syntax: <!-- goatboat: … --> in Markdown or HTML, // in TypeScript.

Prior art

Every system that needs stable identity across renames ends up writing the ID down somewhere:

  • Dendron puts id: in note front matter.
  • Docusaurus separates id from slug.
  • Storybook added an explicit id after URLs broke on title changes.
  • Unity and Godot use sidecar files with a GUID.
  • i18n libraries and feature flags use string keys in code.
  • Terraform uses explicit moved blocks, which make the human declare the rename.

Consequences

  • Moves are exact and keep all metadata and history.
  • Failure is visible: a page missing its marker shows up as a new row.
  • Each page costs one line, and new pages need the scaffold script.
  • It is portable. Only route discovery is framework-specific (the Next adapter in routes-sync.mts). A move to Vite would replace about 20 lines of discovery and leave the marker, the payload and goatboat's matching unchanged.
  • moveContent refusing approute rows ("move the folder instead") now has a working story: the move happens in code, and the sync applies it to the same row.
  • Routes as data

    Proposal: give every page, including TSX ones, a row in the content database.

  • Content tree

    Every node nested under its parent. Paths, and so URLs, come from this tree.

  • Tags

    Every tag with its count. Each links to the feed filtered by that tag.

  • Projects

    Every project and experiment, any status, with kind and status shown.