feat(docs): create docs site at t3.codes/docs

[voltcrash]

The user guides in docs/user could only be read on GitHub, and the README said there was no docs site.

This adds Astro Starlight to the existing marketing site, so the guides are served at t3.codes/docs with search, a sidebar, and a table of contents on each page. It deploys with the marketing site, so there's no new app or Vercel project.

How it works

• One source. A glob loader in apps/marketing/src/content.config.ts reads docs/user/*.md from where they already live, so GitHub and the site render the same files.
• Titles. Each page's # H1 is now a frontmatter title, which Starlight requires.
• Links. Pages still link to each other as ./page.md#anchor, which works on GitHub. A small Sätteri link plugin (Astro 7's default markdown engine) rewrites those links to /docs/page/#anchor on the site. Heading anchors use the same slugger as GitHub, so existing #anchors resolve.
• Landing page. The new docs/user/README.md becomes /docs. It's also what GitHub shows when you open the docs/user folder.
• Sidebar. The page order is set in apps/marketing/astro.config.mjs. docs/README.md now points there instead of keeping a second list.
• Rest of the site unchanged. Starlight's 404 route is disabled and its CSS only loads on /docs pages.
• Looks like t3.codes. Overrides in apps/marketing/src/components/docs/ and src/styles/docs.css replace Starlight's stock look with the site's:
  • the T3 Code / Docs wordmark on the left, with search, the Download link, and the GitHub stars pill grouped on the right of the header;
  • dark-only, since the site is dark-only (no theme picker);
  • zinc palette (muted text lightened to meet 4.5:1 contrast), hairline borders, and the film grain;
  • the homepage's hero grid behind each page title;
  • code blocks as the homepage's terminal window;
  • an accent rail marking the current page in the sidebar and table of contents;
  • tables and previous/next links as hairline tiles.
• Adds a Docs link to the marketing nav and footer.
• Adds one line to AGENTS.md covering the three rules for new user docs: frontmatter title, ./page.md links, and a sidebar entry.
• Bumps astro from 7.2.8 to 7.3.4 to satisfy Starlight 0.42's peer range. 7.3.4 already clears the release-age gate, so there are no workspace exclusions.

Screenshots

Before: t3.codes/docs doesn't exist. The guides are only on GitHub.

After:

/docs

/docs/install/

Mobile (iPhone 12 Pro)

Homepage nav with the new Docs link:

Verification

• vp run build in apps/marketing builds all 27 doc pages plus the Pagefind search index. The only warning is Starlight's standard "i18n collection is empty".
• Checked the built HTML: cross-page links point to /docs/..., anchors match, and the homepage loads no Starlight CSS.
• vp test run src/lib/docsLinks.test.ts and astro check pass. Lint, format, and knip are clean for the changed files.
• Clicked through the built site with astro preview on desktop and an iPhone 12 Pro viewport: search, sidebar, table of contents, tables, code blocks, and the mobile menu.

Replaces #13420, which was closed only to move this work to a better-named branch. Its CodeRabbit contrast finding is fixed here.

🤖 Generated with Claude Code (Claude Opus 5.5, running in T3 Code)

Summary by CodeRabbit

• New Features
  • Published user guides at t3.codes/docs, with a categorized sidebar, search, and links to download and GitHub.
  • Added a documentation landing page with links to setup, usage, and support resources.
  • Added documentation links to the site navigation and footer.
• Documentation
  • Updated guide titles and links for the published documentation site.

[macroscopeapp]

🟡 Medium layouts/Layout.astro:83

The added Docs link makes the non-wrapping mobile header wider than a 390px viewport, so the right side of the navigation—including the new link—is clipped and unreachable. Remove this header item (the footer still provides a Docs link), or hide it at phone widths.

-            <a class="nav-link" href="/docs/">Docs</a>

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/marketing/src/layouts/Layout.astro around line 83:

The added `Docs` link makes the non-wrapping mobile header wider than a 390px viewport, so the right side of the navigation—including the new link—is clipped and unreachable. Remove this header item (the footer still provides a `Docs` link), or hide it at phone widths.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a substantial production-facing docs site, including new routing, search, components, styling, and build dependencies rather than merely editing documentation. An unresolved Medium-severity finding also identifies clipped mobile navigation caused by the new marketing header link.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[tamimbinhakim]

idk. if someone reads docs these days themselves. I ask my claude code to install t3 code lol

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: c54753c7-f98d-4f7a-a9e7-8735aea18395

📥 Commits

Reviewing files that changed from the base of the PR and between 4f27a84 and 561f115.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (42)

• AGENTS.md
• README.md
• apps/marketing/astro.config.mjs
• apps/marketing/package.json
• apps/marketing/src/components/docs/Header.astro
• apps/marketing/src/components/docs/SiteTitle.astro
• apps/marketing/src/components/docs/SocialIcons.astro
• apps/marketing/src/components/docs/ThemeProvider.astro
• apps/marketing/src/components/docs/ThemeSelect.astro
• apps/marketing/src/content.config.ts
• apps/marketing/src/layouts/Layout.astro
• apps/marketing/src/lib/docsLinks.test.ts
• apps/marketing/src/lib/docsLinks.ts
• apps/marketing/src/styles/docs.css
• docs/README.md
• docs/user/README.md
• docs/user/appearance.md
• docs/user/background-service.md
• docs/user/browser-import.md
• docs/user/composer.md
• docs/user/devices.md
• docs/user/install.md
• docs/user/keybindings.md
• docs/user/keyboard-focus.md
• docs/user/mobile-notifications.md
• docs/user/open-source-licenses.md
• docs/user/permission-modes.md
• docs/user/project-settings.md
• docs/user/providers-antigravity.md
• docs/user/providers-claude.md
• docs/user/providers-codex.md
• docs/user/providers-opencode.md
• docs/user/question-attachments.md
• docs/user/remote-access.md
• docs/user/snap-shot.md
• docs/user/source-control.md
• docs/user/telemetry.md
• docs/user/terminal.md
• docs/user/thread-sidebar.md
• docs/user/updating.md
• docs/user/usage.md
• docs/user/welcome-wizard.md

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The marketing app now publishes user guides through Starlight. It loads Markdown files from docs/user/, maps them to documentation routes, and rewrites eligible relative Markdown links. The change also adds site navigation, custom documentation components and styles, and frontmatter titles to the guide pages.

Changes

User documentation site

Layer / File(s)	Summary
User guide content and authoring conventions AGENTS.md, README.md, docs/README.md, docs/user/*.md	Publication guidance and README pages point to the published guides. User guide pages use frontmatter titles, and the new landing page links to selected guides.
Markdown loading and route integration apps/marketing/package.json, apps/marketing/astro.config.mjs, apps/marketing/src/content.config.ts, apps/marketing/src/lib/docsLinks.ts, apps/marketing/src/lib/docsLinks.test.ts	The marketing app adds Starlight and Satteri, configures a docs collection and categorized sidebar, maps Markdown filenames to route IDs, and rewrites eligible relative Markdown links. Tests specify expected link handling.
Documentation presentation and site navigation apps/marketing/src/components/docs/*, apps/marketing/src/styles/docs.css, apps/marketing/src/layouts/Layout.astro	Custom components and styles define the docs header, branding, social links, dark theme, and responsive presentation. The marketing navigation and footer link to /docs/.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant DocsMarkdown as docs/user Markdown
  participant DocsCollection as Astro docs collection
  participant docsEntryId
  participant SatteriPlugin as t3-docs-links plugin
  participant docsHref
  participant Starlight
  DocsCollection->>DocsMarkdown: Load Markdown files
  DocsCollection->>docsEntryId: Generate route IDs
  SatteriPlugin->>docsHref: Resolve relative Markdown URLs
  docsHref-->>SatteriPlugin: Return rewritten route or original URL
  DocsCollection->>Starlight: Provide docs entries validated with docsSchema

Loading

Suggested reviewers: t3dotgg, juliusmarminge

Merge Risk: ⚪ Minimal · up to 561f1

No concrete issue with the published guides or documentation site is established; the PR appears ready for normal merge checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 561f1

The new pages publish guides through the existing marketing site. The reviewed changes do not establish a new privileged endpoint or a verified security issue, but the additional public rendering surface warrants review.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The added exposure is public documentation on the marketing site's origin. The reviewed route and collection changes do not show a new privileged API, credential use, or user-submitted content source.

Trust Boundaries and Controls

• inferred — Repository modification, rather than an anonymous page request, controls the Markdown selected for publication by the scoped glob loader. Repository content-approval controls were not established by the available evidence.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states that the pull request creates a documentation site at t3.codes/docs. It matches the primary change.
Description check	✅ Passed	The description explains what changed, why it changed, implementation details, UI changes, screenshots, and verification steps. It omits the template's explicit Checklist section, but the required inf…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files. (38 skipped: 3…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}