feat(frontend): serve the documentation from the frontend

[marcalexiei]

Implements option A of #461.
(Closes #461)

Serving the docs from the frontend at /frontend/docs ships them with the API in one commit, so samples resolve against the deployment serving them.

Documentation PRs can be merged as soon as they are approved.
Nothing they add reaches users until the same release promotion that ships the code they describe, so there is no longer a reason to hold an approved PR back until just before a release, and nothing to re-check afterwards.

Note

Please look at the documentation layout and the general approach before the code, and say whether that is the direction we want to take. The code is easy to adjust afterwards.
I asked Claude Opus 5 to help build the docs site, so most of apps/frontend/src/docs and its styling come from there, with follow up adjustments by me.

Try it

pnpm dev:frontend

Then open http://localhost:5173/frontend/docs.
The wizard links to it from the header, and from steps 3 and 4.

Summary

Changes

• Add frontend/docs route in the existing app, wizard and docs lazy-loaded so neither pays for the other.
• Markdown compiled at build time by vite-plugin-markdown, with markdown-it-github-alerts for > [!NOTE] blockquotes.
  Nothing markdown-related reaches the browser.
• Heading ids and per-heading permalinks via markdown-it-anchor, at build time.
• transformDocHtml resolves what the compiler doesn't: repo-relative links to ?page= queries, hosted card URLs to site-relative.
• docs/index.md as a docs-specific overview, with README.md trimmed to a landing page linking to it.
• apps/frontend/src/ split into docs/, wizard/ and shared/; AppTrends renamed to Wizard.
• Wizard doc links now point at the docs route instead of the markdown on master,
  through a docsUrl helper typed from the page list, so a renamed page breaks the build.
• LinkExternal replaces the hand-repeated target/rel pairs and marks new-tab links with an icon (which can be disabled via prop).
• vercel-preparation.sh copies the entry point to static/frontend/docs/, keeping the output filesystem based.

Why some rewriting is at build time and some at runtime

Any rewriting is needed at all because the sources are read in two places:
on github.com they have to work as they are, so they keep absolute card URLs and repository-relative .md links,
while the site needs those pointing at the serving deployment and at ?page= routes.

Heading ids and their permalinks are markdown, so markdown-it-anchor handles them during the build.
The rest stays in transformDocHtml, because two cases markdown-it cannot see:

• Raw HTML. Most card samples are hand-written <picture><source srcset="…"> blocks, which markdown-it emits as opaque html_block tokens, so renderer rules never touch them.
• Local images. frontend-screenshot.png has to become a hashed Vite asset URL, which only the bundler knows.

Only 24 of the 251 hosted URLs are raw HTML; the rest is markdown syntax.
So if the site ever becomes the only place the docs are read, those blocks could go site-relative, the rest could move into markdown-it rules, and transformDocHtml could go away.

[vercel]

@marcalexiei is attempting to deploy a commit to the martin-mfg's projects Team on Vercel.

A member of the Team first needs to authorize it.