The 404 router, and a site with two modes: notes on the URL article

The 404 router, and a site with two modes: notes on the URL article

Status: the editor's notes on reading 2026-10-25__brief__urls-personas-and-a-single-page-site.md, captured as he gave them (a word in square brackets is a correction of the transcription), with story-site's reply. Not built. Author: story-site (claude-story-site), 25 October 2026, in its session with the editor. This changes the article in one important way: persona paths are no longer files the build writes, they are paths that do not exist, answered by a 404.html that works as the router.

The editor's notes, in his words

"I'm thinking that this may actually be quite good to also, without you actually having to have a lot of server-side components, or even, you might even clean up, because while I was thinking that you can actually produce an MD view or a JSON view, which we should for every single page, although if this is SPA, it will require a little bit of JavaScript. So maybe we still put it on the browser, but you give instruction in the source code for the agent to go, by the way, this is where the content will go, so go and read this." "I love this URL path ... which is basically /agencies/{persona details}, /agencies/aaa/{persona details}, /xyz/aaa/bbbb/{persona details}, with /agencies, /xyz, /{content pages} being the main (and indexed pages)." "You have two modes of operating the site. You have a mode, which actually can be very SEO friendly, which is, you can always follow by the main page ... that's all the original content that's not persona specific of that page, kind of what we have now." "Because this runs on GitHub Pages, you're going to have to create a 404 page, which basically means that the first time that you hit that page with the path, you're going to get a 404, because that path doesn't exist. And like I said, I don't think we should have any server-side paths on those personas or those messages, because that will explode. But if you think about it, the date could change ... You could even have a diff of dates." "I really love the fact that you [can] use the path. It's almost a search criteria ... just from the path you can see what you're going to get, which makes it easy to share, easy to link. The first part of the path is the real page ... The second part of the path is the customization. I think the as is the breaking point. The as page never exists, but it's your indicator." "If you hit the homepage, if you don't have any personalization, we just shift you to as executive. So immediately you see the executive. And I think what's cool about this is you can actually do this on top of [what we have], because we're just going to be changing just about all of the UI."

What this changes from the article

The shape of an address

/agencies/                                   the page (a real file; indexed)
/agencies/as/security/                       a view: the page for Security
/agencies/as/security/deep/                  ... at the deepest wording
/agencies/on/2026-10-23/                     a view: the page as it stood on the 23rd
/agencies/on/2026-10-21/vs/2026-10-23/       a view: what changed between two dates
/agencies/as/journalist/on/2026-10-23/       criteria combine, in any order after the page

The rule: the page is everything before the first reserved word; everything after it is criteria. The reserved words are short and few: as, on, vs, since. The build checks that no real page has a path segment equal to one of them, so the split is never ambiguous.

story-site's view

The editor's version is better than the article's, and simpler. Five things to get right, three of which are only visible once you try to build it:

1. The 404 status is a feature. GitHub Pages answers 404.html with HTTP status 404 (checked: /agencies/as/security/ returns 404 today). A crawler that follows a view path gets a 404 and does not index it. That is exactly what view paths should be: the article needed canonical tags on hundreds of files to say this; here the status says it for free, and only the real pages are ever indexed.

2. The one cost: link previews. When a view path is pasted into Slack, Teams or iMessage, the preview is fetched without running JavaScript, so it shows 404.html's own title and card, not "The agencies, as Security". Two answers, cheap first: give 404.html a good neutral card ("PHP October 2026: this page, written for you"); and, if previews matter for the most-shared link, write real files for the front page's seven views only (seven files, not hundreds) so the first link people share unfurls properly. Everything else stays virtual.

3. Relative links, and the site's security policy. Every page links with relative paths (../agencies/index.html). Served at /agencies/as/security/, those resolve against the wrong directory and break. The usual fix, a <base href>, is blocked by the site's Content-Security-Policy (base-uri 'none'), on purpose. So the router resolves every link against the real page's address itself (new URL(href, pageURL)), which needs no change to the policy and no review by security.

4. Do not redirect the front page to /as/executive/. The Executive is already the default, and the line already says it ("You're viewing this as an Executive") on the first paint. Sending / to a path that answers 404 risks search engines dropping the front page: they follow script redirects, and they would land on a 404. Instead: / is the Executive's view; when a reader picks another role, the address bar changes to /as/security/ in place (history.replaceState), so copying the address shares the view; going back to the default takes the segment away. The editor's aim, that the reader immediately sees the Executive view and knows it, is kept; the risk is not.

5. A markdown and a JSON view of every page, and a note for agents. Every page already has its markdown twin (index.md) and is in llms.txt. Add page.json beside it: the page's parts as data, with the roles each is for, so a view can be assembled in the browser and read by an agent without any script. In each page's source, the pointers are plain facts, never addressed to a model: <link rel="alternate" type="application/json" href="page.json"> and <link rel="alternate" type="text/markdown" href="index.md">, plus one line in 404.html's source saying that a view path is the page before the first reserved word, shaped by the criteria after it, with the data in that page's page.json. (The site's gate rejects text that addresses a model; this passes it because it describes, it does not instruct.)

And it does sit on top of what exists. The real pages are today's pages. 404.html, the router and page.json are additions; nothing that works today stops working, and a reader without JavaScript on a view path still gets a page with a link to the real one.

The order

1. 404.html as the router: parse the path at the first reserved word, fetch the real page, resolve its links, hand the criteria to the line. Real pages unchanged. The gate learns the reserved words.

2. The address bar follows the reader's view (replaceState); the line's "Share this view" copies the view path.

3. page.json beside every page, and the alternate links.

4. Dates (on), then diffs (vs, since), from the releases the site already keeps.

5. Fragments and in-page navigation, the single-page part, last (the article, section 4).

Decisions for the editor

1. Previews: a neutral card only, or also seven real files for the front page's views.

2. The front page: / stays the Executive's view with no redirect, and the address changes only when a reader picks another role (recommended), or a redirect to /as/executive/ as first proposed, knowing the indexing risk.

3. The reserved words: as, on, vs, since; any others.

4. When: after the line is live on the reader pages (board 297), since the router hands its criteria to the line.