docs: small frontmatter and style contract so docs/ can sync into developer-docs

[marc0olo]

What we want to do

Publish the eight pages in docs/ on docs.internetcomputer.org as the Frontends section of the ICP developer docs, synced from this repo, with this repo staying the single source of truth. @dfinity/static-site is becoming the primary way we advertise deploying a frontend on ICP (the icp-cli templates already ship it, and docs.internetcomputer.org is itself deployed with it), so these pages need a published home. Right now they are only readable on GitHub.

The alternative is that we paraphrase them in the developer-docs repo, which means two copies drifting apart. Nobody wants that.

How the sync would work

A script in the developer-docs repo fetches docs/*.md at a release tag, applies a short mechanical pass, and commits the result under docs/guides/frontends/static-site/. A weekly workflow opens the bump PR when a new release lands. No git submodule, because these pages have no build-time file includes.

Two properties of this repo make it the easiest sync we would have:

• Your tag is the version users type. v0.3.3 here matches static-site-v0.3.3 in icp-cli-recipes, released the same day. One pin identifies both the docs and the recipe, so the published page can state the version it documents without us guessing.
• Your links already match the target conventions. 40 of 43 links in docs/ are relative .md links or in-page anchors, which is exactly what developer-docs requires.

The precedent is caffeinelabs/motoko, whose doc/md/ tree syncs into docs/languages/motoko/ (76 pages) as a plain rsync plus a small postprocess. That sync is cheap because upstream carries a little frontmatter. This proposal is the same contract, scaled to eight files.

What we are NOT asking for

To be clear about the size of the ask:

• No restructuring, no file renames, no splitting or merging pages.
• No Starlight or MDX components, no JSX, no import statements.
• No losing GitHub readability. We are not asking you to remove the # H1 (see the open question at the end).
• No writing for our sidebar. Eight flat pages need an order number, not a navigation manifest.

The asks

1. title in frontmatter (required, build fails without it)

Starlight's docsSchema() requires a title. This is the only item that is a hard blocker rather than a preference.

2. description and sidebar.order (wanted)

description becomes the page meta description and the sidebar tooltip; developer-docs requires it on every hand-written page. sidebar.order sets the sequence, which is all the navigation input we need for a flat folder.

Here is a concrete proposal for all eight files, so this is a review task rather than a writing task. Adjust freely; the exact wording is yours.

File	title	description	order
overview.md	Static site overview	Deploy a static site to a certified assets canister with the static-site recipe	1
routing.md	Routing and clean URLs	How request paths resolve to files, clean URLs, trailing slashes, 404 handling, and single-page apps	2
redirects.md	Redirects and rewrites	The _redirects file: permanent and temporary redirects, rewrites, subtree moves, and custom error pages	3
headers.md	Custom headers	The _headers file: cache-control, security headers, content types, and how rules combine	4
site-files.md	Site files and conventions	What gets uploaded, the special _redirects and _headers files, skipped files, custom domains, and the 404 page	5
access-protection.md	Access protection	Put a login page in front of a private or preview site with revocable, expiring access tokens	6
verifying-contents.md	Verifying contents	Prove a canister serves exactly a known build by reproducing its state hash from source	7
how-it-works.md	Under the hood	How the canister certifies responses, serves large assets, negotiates encodings, and persists state across upgrades	8

The block looks like this (copied from caffeinelabs/motoko doc/md/fundamentals/pattern-matching.md):

---
title: "Routing and clean URLs"
description: "How request paths resolve to files, clean URLs, trailing slashes, 404 handling, and single-page apps"
sidebar:
  order: 2
---

Note that two titles differ slightly from the current H1s: routing.md and redirects.md use "and" instead of "&", and overview.md becomes "Static site overview" rather than a bare "Overview", because the developer-docs sidebar has many overviews and a generic label is not navigable there. If you keep the H1, it can stay exactly as it reads today.

3. Drop the em-dashes (style)

developer-docs bans the em-dash (U+2014) repo-wide; its validator fails the build on one in prose. There are 124 in docs/ today:

File	Count
access-protection.md	23
overview.md	20
headers.md	16
how-it-works.md	16
redirects.md	16
verifying-contents.md	16
routing.md	11
site-files.md	6

Being straight about the leverage here: the developer-docs validator exempts synced trees from every check, so this is not a build blocker. It is a consistency choice, and there are two ways to land it.

• You drop them. The published text and the repo text stay identical, which is the property that makes a sync trustworthy.
• Our script rewrites them. Works today, costs you nothing, but the published page then differs from the file in this repo, so a reader comparing them sees edits that nobody in this repo made.

We would rather have the first. It is a mechanical pass (colon, semicolon, comma, or parentheses depending on the sentence) and it is the only ask that touches how your team writes.

4. Keep the <version> placeholder convention

docs/overview.md already writes @dfinity/static-site@<version> with a pointer to the releases page rather than hardcoding a number. Please keep that. The developer-docs habit of pinning exact versions in prose is how we ended up with @dfinity/asset-canister@v2.2.1 in nine places while upstream is on v2.3.0.

One small correction while we are here: the example version in overview.md reads (e.g. v1.0.0), but the latest release is v0.3.3. Worth changing to avoid implying a 1.x exists.

5. Two link fixes

• docs/site-files.md links to https://docs.internetcomputer.org/building-apps/frontends/custom-domains/using-custom-domains, which is the retired portal URL format. It currently survives on a redirect. The live page is https://docs.internetcomputer.org/guides/frontends/custom-domains/.
• Three links escape docs/ and would break once synced: ../ARCHITECTURE.md, ../README.md#releasing, ../examples/spa/. Our script can rewrite them to permalinks at the synced tag, but if you would rather they be absolute GitHub URLs in the source, that removes the rewrite entirely.

What stays on our side

So it is clear where the boundary is. Our postprocess will:

• strip the H1 if you keep it, since Starlight renders the title from frontmatter;
• rewrite the two docs.internetcomputer.org links to site-relative paths (they are internal links once published);
• rewrite any remaining out-of-docs/ relative link to a GitHub permalink at the synced tag;
• stamp the source repo and tag on each page so readers can see exactly which release they are reading;
• not require a ## Next steps section. developer-docs mandates one on hand-written pages and exempts synced trees. Zero of the 76 synced Motoko pages have one.

And these topics stay hand-written in developer-docs rather than being pushed upstream, because they are platform concerns rather than canister behavior: registering a custom domain (DNS walkthrough per registrar), the response certification concept and client-side certificate verification, framework integration (React, Vue, Svelte, Next.js), Internet Identity and alternative origins, and a migration guide from the old asset canister. Your site-files.md already links to us for domain registration, which is exactly the right direction. Please keep doing that instead of duplicating it here.

Open question

Keep the H1 or go full Motoko parity?

caffeinelabs/motoko dropped the H1 because doc/md/ exists mainly to feed the docs site. Here, docs/ is a primary reading surface: your README sends people straight to it. Keeping the H1 costs you a duplicated title string per file and a small YAML table rendered above it on GitHub; dropping it makes the sync a pure rsync but leaves the GitHub view with no visible title.

Our recommendation is keep the H1. Stripping it is three lines in our script and it is not worth degrading how these pages read in the repo.

Related

#123 asks whether the canister should refuse raw hosts. That answer changes what we publish about certification guarantees, so it would be good to settle it before these pages go live.