From 43a2f3a06929b13258db104ce86661c2cbcd252e Mon Sep 17 00:00:00 2001 From: Bendik Lynghaug Date: Wed, 7 Oct 2026 10:31:21 +0200 Subject: [PATCH] Document files at the site root Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_015GeH3y8fwTaTudaD88P57o --- docs/content-reference.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/content-reference.md b/docs/content-reference.md index 2bc89b3..290bef2 100644 --- a/docs/content-reference.md +++ b/docs/content-reference.md @@ -97,6 +97,35 @@ Pictures in the content repo are served from this origin under `/site/`; `webp`, `avif` and `jpeg` may be kept by the browser for an hour. Keep them web-sized: around 1400 pixels tall is plenty. +## Files at the site root + +A repo's `.well-known/` directory is served at the root of the site, at +the same paths it has in the repo: + +``` +.well-known/security.txt -> https:///.well-known/security.txt +.well-known/assetlinks.json -> https:///.well-known/assetlinks.json +.well-known/matrix/server -> https:///.well-known/matrix/server +``` + +This is the one part of the URL space a repo may write into directly. +RFC 8615 reserves `/.well-known/`, and a question's id comes from a file +name under `questions/`, which cannot begin with a dot - so nothing +shipped here can shadow a page. A path that is not in the repo answers +**404**, not the app shell, so a program looking for one of these can +tell a missing file from a present one. + +A file with no extension is served as JSON, which is what the +extensionless well-known files are. `.txt`, `.xml`, `.webmanifest` and +`.mobileconfig` are typed as themselves; the last matters because iOS +only offers to *install* a configuration profile that arrives as +`application/x-apple-aspen-config`. + +Paths a reverse proxy claims in front of portal never reach the repo - +mail autoconfiguration (`/.well-known/autoconfig/`) and the CalDAV and +CardDAV redirects are usually handed to a mail server that generates +them. + ## An alternative One choice. Never two actions behind one heading: if two things can be