[Docs][Content] - Rework overview page and slight updates to codeblocks #1056
Conversation
…taining important links
Older cmux preview screenshots (latest comment is below)Preview ScreenshotsOpen Workspace (1 hr expiry) · Open Dev Browser (1 hr expiry) · Open Diff Heatmap Captured 1 screenshot for commit Full page screenshot of the docs Overview page showing the welcome section, quick link cards for Setup & Installation, Components, SDK Reference, and REST API Reference. Also shows the Apps section with icon grid (API Keys, Emails, Teams, RBAC, Webhooks), Why Choose Stack Auth section with code examples, and sign-in component preview. Generated by cmux preview system |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds an "overview" examples section, restructures the docs overview page into a quick-start/components layout, extends frontmatter with an optional lastModified field, renders "Last updated" on doc pages when present, and adds a copy-to-clipboard button to code blocks. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile OverviewGreptile SummaryThis PR redesigns the documentation overview page and adds quality-of-life improvements to code blocks. Key Changes:
Technical Notes:
Confidence Score: 5/5
Important Files ChangedFile Analysis
Sequence DiagramsequenceDiagram
participant User
participant OverviewPage as overview.mdx
participant PlatformCodeblock
participant BaseCodeblock
participant Clipboard as navigator.clipboard
User->>OverviewPage: Visit /docs/overview
OverviewPage->>PlatformCodeblock: Render with document="setup/overview"
PlatformCodeblock->>PlatformCodeblock: getExample("setup/overview", "install")
PlatformCodeblock->>BaseCodeblock: Render code with copy button
User->>BaseCodeblock: Hover over code block
BaseCodeblock->>BaseCodeblock: Show copy button (opacity-100)
User->>BaseCodeblock: Click copy button
BaseCodeblock->>Clipboard: writeText(code)
Clipboard-->>BaseCodeblock: Success
BaseCodeblock->>BaseCodeblock: Show checkmark, reset after 2s
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/src/components/mdx/base-codeblock.tsx (1)
4-4: Tighten copy handler error handling and hover behavior; consider using shared icons
- Since the click is already wrapped in
runAsynchronously, you can drop the localtry/catchinhandleCopyand let the shared helper surface/log errors, keeping behavior consistent with the rest of the app. If you still want custom UX on failure, userunAsynchronously’sonErroroption rather than swallowing insidehandleCopy.- The code‑trimming (
code.startsWith(' ') ? code.slice(1) : code) is now duplicated between highlighting and copying; consider extracting a smallgetSanitizedCode(code)helper to keep them in sync.- The button’s
transition-allwithopacity-0 group-hover/code:opacity-100currently fades in on hover as well as out; per the hover guidelines, you may want to make the appearance snappier and only animate the fade‑out (e.g., keep the hover state immediate and transition opacity/colors on hover exit).- You already have
CheckandCopyicons defined indocs/src/components/icons.tsx; importing from there instead oflucide-reactdirectly would keep icon usage consistent and avoid duplicate definitions.Also applies to: 52-62, 164-180
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/code-examples/setup.ts(1 hunks)docs/content/docs/(guides)/overview.mdx(2 hunks)docs/source.config.ts(1 hunks)docs/src/app/docs/[[...slug]]/page.tsx(1 hunks)docs/src/components/mdx/base-codeblock.tsx(3 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: Always add new E2E tests when changing the API or SDK interface
For blocking alerts and errors, never use toast; use alerts instead as they are less easily missed by the user
NEVER try-catch-all, NEVER void a promise, and NEVER .catch(console.error); use loading indicators and async callbacks instead, or use runAsynchronously/runAsynchronouslyWithAlert for error handling
Use ES6 maps instead of records wherever you can
Files:
docs/code-examples/setup.tsdocs/source.config.tsdocs/src/app/docs/[[...slug]]/page.tsxdocs/src/components/mdx/base-codeblock.tsx
**/*.{ts,tsx,css}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx,css}: Keep hover/click transitions snappy and fast; avoid fade-in delays on hover. Apply transitions after action completion instead, like smooth fade-out when hover ends
Use hover-exit transitions instead of hover-enter transitions; for example, use 'transition-colors hover:transition-none' instead of fade-in on hover
Files:
docs/code-examples/setup.tsdocs/source.config.tsdocs/src/app/docs/[[...slug]]/page.tsxdocs/src/components/mdx/base-codeblock.tsx
{.env*,**/*.{ts,tsx,js}}
📄 CodeRabbit inference engine (AGENTS.md)
Prefix environment variables with STACK_ (or NEXT_PUBLIC_STACK_ if public) so changes are picked up by Turborepo and improves readability
Files:
docs/code-examples/setup.tsdocs/source.config.tsdocs/src/app/docs/[[...slug]]/page.tsxdocs/src/components/mdx/base-codeblock.tsx
🧠 Learnings (1)
📚 Learning: 2025-12-04T18:03:49.961Z
Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.961Z
Learning: Applies to packages/stack-shared/src/config/schema.ts : Whenever making backwards-incompatible changes to the config schema, update the migration functions in packages/stack-shared/src/config/schema.ts
Applied to files:
docs/source.config.ts
🧬 Code graph analysis (1)
docs/src/components/mdx/base-codeblock.tsx (2)
packages/stack-shared/src/utils/promises.tsx (1)
runAsynchronously(343-366)docs/src/components/icons.tsx (2)
Check(163-165)Copy(185-205)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (11)
- GitHub Check: lint_and_build (latest)
- GitHub Check: all-good
- GitHub Check: Vercel Agent Review
- GitHub Check: check_prisma_migrations (22.x)
- GitHub Check: docker
- GitHub Check: restart-dev-and-test
- GitHub Check: build (22.x)
- GitHub Check: build (22.x)
- GitHub Check: setup-tests
- GitHub Check: restart-dev-and-test-with-custom-base-port
- GitHub Check: build (22.x)
🔇 Additional comments (4)
docs/source.config.ts (1)
7-12: Extended frontmatter schema wiring looks correct and backwards‑compatibleUsing an optional
lastModifiedstring on top of the existingfrontmatterSchemacleanly adds the metadata without breaking existing docs, and scoping it only to the main docs collection is appropriate. No further changes needed here.Also applies to: 18-18
docs/src/app/docs/[[...slug]]/page.tsx (1)
70-75: Last‑updated display is safely integratedThe conditional render on
page.data.lastModifiedis straightforward, non‑disruptive to existing pages, and the styling matches a subtle metadata footer. Looks good as is.docs/code-examples/setup.ts (1)
4-24: Overview quick‑start examples are consistent with existing setupExamples structureThe new
overview.installandoverview.use-authentries fit the existingsetupExamplesshape and align with thePlatformCodeblockusage (document="setup/overview"and matching example keys). This should wire the Quick Start section cleanly into the existing code‑example system.docs/content/docs/(guides)/overview.mdx (1)
3-3: Overview page rework and lastModified metadata are coherent with the new quick‑start flowThe updated frontmatter
lastModifiedfield, hero, Quick Start (wired tosetup/overviewexamples), Components, Explore, and Apps sections form a clear, concise entry point into the docs. The new links and PlatformCodeblock usage line up with the code‑examples configuration, and the content structure stays compatible with the new last‑updated footer rendering.Also applies to: 6-39, 57-57, 70-70, 80-80
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/source.config.ts (1)
9-12: Consider adding date format validation.The
lastModifiedfield accepts any string. For consistency across documentation pages, consider validating the date format:const extendedFrontmatterSchema = frontmatterSchema.extend({ - lastModified: z.string().optional(), + lastModified: z.string().datetime().optional(), // ISO 8601 format });Alternatively, if you prefer a simpler date format like
YYYY-MM-DD:lastModified: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),This ensures consistent date formats and catches typos in frontmatter early during build.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/source.config.ts(3 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: Always add new E2E tests when changing the API or SDK interface
For blocking alerts and errors, never use toast; use alerts instead as they are less easily missed by the user
NEVER try-catch-all, NEVER void a promise, and NEVER .catch(console.error); use loading indicators and async callbacks instead, or use runAsynchronously/runAsynchronouslyWithAlert for error handling
Use ES6 maps instead of records wherever you can
Files:
docs/source.config.ts
**/*.{ts,tsx,css}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx,css}: Keep hover/click transitions snappy and fast; avoid fade-in delays on hover. Apply transitions after action completion instead, like smooth fade-out when hover ends
Use hover-exit transitions instead of hover-enter transitions; for example, use 'transition-colors hover:transition-none' instead of fade-in on hover
Files:
docs/source.config.ts
{.env*,**/*.{ts,tsx,js}}
📄 CodeRabbit inference engine (AGENTS.md)
Prefix environment variables with STACK_ (or NEXT_PUBLIC_STACK_ if public) so changes are picked up by Turborepo and improves readability
Files:
docs/source.config.ts
🧠 Learnings (1)
📚 Learning: 2025-12-04T18:03:49.961Z
Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.961Z
Learning: Applies to packages/stack-shared/src/config/schema.ts : Whenever making backwards-incompatible changes to the config schema, update the migration functions in packages/stack-shared/src/config/schema.ts
Applied to files:
docs/source.config.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (11)
- GitHub Check: setup-tests
- GitHub Check: restart-dev-and-test
- GitHub Check: restart-dev-and-test-with-custom-base-port
- GitHub Check: lint_and_build (latest)
- GitHub Check: all-good
- GitHub Check: Vercel Agent Review
- GitHub Check: build (22.x)
- GitHub Check: check_prisma_migrations (22.x)
- GitHub Check: docker
- GitHub Check: build (22.x)
- GitHub Check: build (22.x)
🔇 Additional comments (1)
docs/source.config.ts (1)
16-45: LGTM!The extended schema is consistently applied across all three documentation collections (docs, api, dashboard), ensuring uniform frontmatter support for the
lastModifiedfield throughout the docs site.
Preview ScreenshotsOpen Workspace (1 hr expiry) · Open Dev Browser (1 hr expiry) · Open Diff Heatmap Captured 2 screenshots for commit Overview docs page showing the Welcome header with Stack Auth icon, Quick Start section with PlatformCodeblock components displaying installation and usage code examples with syntax highlighting and platform selector Full Overview docs page showing all UI components: Welcome header, Quick Start code blocks, Components CardGroup with React component links, Explore QuickLinks cards, Apps AppGrid with feature icons, and Last Updated date footer Generated by cmux preview system |
Changes
overview Page Redesign
Frontmatter schema extension
Last Modified Display
Copy Button for Code Blocks
New Code Examples
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.