feat: publish the documentation and the card wizard from one Astro site

[marcalexiei]

• Closes Publish documentation from release instead of master #461

---

• Turns apps/frontend into an Astro + Starlight site.
  Serves the docs at /frontend/docs and the card wizard at /frontend:
  one dev server, one build, one deploy, and no Python in vercel-preparation.sh or in the local setup.
• The wizard becomes a page of that site: a React island on Starlight's splash layout,
  so it inherits the header, footer and search.
  Its own app bar, theme picker and Redux theme slice go away.
  Starlight writes the data-theme daisyUI already reads, so one control themes both halves.
• The *.md sources move to apps/frontend/src/content/docs/docs/ with a title in
  frontmatter and Starlight's :::note asides, which lets Astro resolve their links and
  images natively (no markdown-conversion code of our own).
  starlight-links-validator then fails the build on a dead internal link.
• packages/core/src/themes/README.md is generated into the site instead; README and CONTRIBUTING links follow the move.
• Tailwind now shares a page with Starlight, so index.css declares the cascade-layer order
  (its utilities must outrank Starlight's reset) and scopes the app's element rules under
  .wizard, leaving the site identical on both halves.

---

To try it out just run

pnpm --filter ./apps/frontend run dev

---

Wizard	Documentation

[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.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
github-stats-extended-backend	Ready	Preview	Aug 22, 2026 5:03pm

[marcalexiei]

I made few changes with the last commit (totally fine if you want to go ahead without them):

• Splits the "Advanced Customization" page into smaller pages, grouped in the sidebar under two categories:
  • Cards: one page per card
  • Customization: Common Options, Theming, Available Themes, Locales and Aligning Cards
  
• Moved the options shared by every card out from under "GitHub Stats Card", where they were nested despite applying to all of them.
• Redirects /frontend/docs/advanced_documentation/ to "Common Options" and both group paths to their first page, so published URLs do not hit 404.
• Links each card title in the Overview page's "Card Types" section to that card's page.

[martin-mfg]

I haven't completely reviewed all changes yet. But I reviewed most of them and don't want to keep you waiting longer for initial feedback.

Btw, good idea to go with Astro+Starlight instead of MkDocs. 👍

[martin-mfg]

The theming via #gh-dark-mode-only/#gh-light-mode-only doesn't work here.

[marcalexiei]

The section header now uses <picture>, and the GitHub-only technique says why it has no live preview.
The copyable snippet is unchanged.

[martin-mfg]

The <picture> element currently responds to the browser theme, not to the page theme. Could you fix this please?
edit: preview link

[marcalexiei]

Each preview is now a card-preview-light / card-preview-dark image pair,
with one rule in starlight-theme.css hiding the wrong one per :root[data-theme].
Applied here and to the six previews on the Overview page, which had the same problem.

I also dropped the live example under "Use GitHub's new media feature":
it follows prefers-color-scheme by definition, so it could never match the page theme.
It now has a note instead, like the #gh-dark-mode-only section.

Note the Overview previews still look the same in both themes:
they use light_github / dark_github, which the current deployment does not serve yet.
The swap itself works: the Responsive Card Theme preview uses default / dark and changes correctly.

[martin-mfg]

they use light_github / dark_github, which the current deployment does not serve yet.

I think we should use relative urls like src="/api?username=anuraghazra&theme=light_github" for docs images where applicable. Then we could verify the docs look as expected already on the master branch and don't need to wait for a release to check them. Or am I missing any important downsides?
(They wouldn't work locally anymore, but I think that's ok.)

[marcalexiei]

I think we should use relative urls like src="/api?username=anuraghazra&theme=light_github"for docs images where applicable.

Every live card image now uses /api?..., including the generated theme gallery.

(They wouldn't work locally anymore, but I think that's ok.)

I disagree: it would mean that every docs change waits on a deploy or that you deploy the changes on Vercel preview from the PR.
apps/backend/express.js already exists unused so I wired it up:

• pnpm dev:backend runs the API on :9000
  (it loads PAT_1 from apps/backend/.env; Postgres stays optional, so a token is all a contributor needs).
• pnpm dev:frontend proxies /api there, so the relative URLs resolve while authoring.
• .github/CONTRIBUTING.md documents both.

Notes

1. express.js now strips a trailing slash before the router, because Vercel resolves /api/pin/ to the same function as /api/pin while the router matches paths exactly.
   I dropped all trailing slashes from the docs URLs.
2. starlight-links-validator treated /api?... as internal links, so it now excludes /api.

[marcalexiei]

vercel.json sent / to the GitHub repo, it now redirects to /frontend/docs/.
Since the destination is a path rather than a full URL, a preview lands on its own docs instead of production's.