[docs] Various fixes throughout docs site (#1042)

<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->

# New 
- quick-links component:
Better UI that is more aligned with current styling, as well as centered
on page for better experience.
<img width="812" height="342" alt="image"
src="https://github.com/user-attachments/assets/3de105af-eff0-4ddd-92b4-20c4a388fb03"
/>

# Update
- Updates sidebar with slight visualization to separate Overview, and
FAQ links.
<img width="268" height="471" alt="image"
src="https://github.com/user-attachments/assets/7372f557-f4c5-42d8-9dea-8c3b1b0e5514"
/>

# fixes
- Re-add removed mcp-setup.mdx into /content so its available again. 
- update meta.json to reflect re-added mc-setup.mdx
- centered app-icons on overview page



<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a comprehensive MCP setup guide covering major IDEs and AI
clients.
* Introduced QuickLinks navigation component for enhanced docs
navigation.

* **Documentation**
* Refreshed overview with QuickLinks-based layout and preserved link
targets.
* Added ready-to-copy installation/config snippets and multi-client
setup steps.

* **Style**
* Updated docs sidebar styling and grouping for clearer “Overview”/FAQ
separation.
  * Centered app cards layout and adjusted header nav activation logic.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Madison 2025-12-04 08:45:54 -06:00 committed by GitHub
parent 0197b4bced
commit c63858b50d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 445 additions and 41 deletions

View File

@ -12,27 +12,27 @@ import { UserButton } from "@stackframe/stack";
import { ALL_APPS, type AppId } from "@stackframe/stack-shared/dist/apps/apps-config";
import { typedEntries } from "@stackframe/stack-shared/dist/utils/objects";
import {
Button,
Sheet,
SheetContent,
SheetTitle,
SheetTrigger,
Tooltip,
TooltipContent,
TooltipProvider,
TooltipTrigger,
Typography,
Button,
Sheet,
SheetContent,
SheetTitle,
SheetTrigger,
Tooltip,
TooltipContent,
TooltipProvider,
TooltipTrigger,
Typography,
} from "@stackframe/stack-ui";
import {
Blocks,
ChevronDown,
ChevronRight,
Globe,
KeyRound,
LucideIcon,
Menu,
PanelLeft,
Settings,
Blocks,
ChevronDown,
ChevronRight,
Globe,
KeyRound,
LucideIcon,
Menu,
PanelLeft,
Settings,
} from "lucide-react";
import { usePathname } from "next/navigation";
import { useCallback, useMemo, useRef, useState } from "react";

View File

@ -44,6 +44,7 @@
"others/self-host",
"others/supabase",
"others/convex",
"others/mcp-setup",
"sdk",
"components"
]

View File

@ -0,0 +1,240 @@
---
title: MCP Setup
---
<div className="flex items-center justify-center gap-8 mb-8">
<StackAuthIcon size={128} />
<div className="text-3xl font-light text-fd-muted-foreground">+</div>
<img src="/imgs/mcp.svg" alt="MCP" width="128" height="128" className="flex-shrink-0 dark:invert" />
</div>
Set up Stack Auth's Model Context Protocol (MCP) server to get intelligent code assistance in your development environment.
<Tabs defaultValue="cursor">
<TabsList>
<TabsTrigger value="cursor">Cursor</TabsTrigger>
<TabsTrigger value="vscode">VS Code</TabsTrigger>
<TabsTrigger value="claudecode">Claude Code</TabsTrigger>
<TabsTrigger value="claudedesktop">Claude Desktop</TabsTrigger>
<TabsTrigger value="windsurf">Windsurf</TabsTrigger>
<TabsTrigger value="chatgpt">ChatGPT</TabsTrigger>
<TabsTrigger value="gemini">Gemini CLI</TabsTrigger>
</TabsList>
<TabsContent value="cursor">
Configure Stack Auth MCP in Cursor IDE for enhanced code assistance.
<Button href="cursor://anysphere.cursor-deeplink/mcp/install?name=stack-auth&config=eyJ1cmwiOiJodHRwczovL21jcC5zdGFjay1hdXRoLmNvbS8ifQ==" icon={<img src="/imgs/cursor.svg" alt="Cursor" width="14" height="14" className="w-full h-full object-contain" />}>Add to Cursor</Button>
**Manual Installation**
Add the following to your `mcp.json` file:
```json title="mcp.json"
{
"mcpServers": {
"stack-auth": {
"url": "https://mcp.stack-auth.com/"
}
}
}
```
</TabsContent>
<TabsContent value="vscode">
Configure Stack Auth MCP in VSCode IDE for enhanced code assistance.
<Button href="https://insiders.vscode.dev/redirect?url=vscode:mcp/install?%7B%22type%22%3A%22http%22%2C%22name%22%3A%22stack-auth%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.stack-auth.com%2F%22%7D" icon={<img src="/imgs/vscode.svg" alt="VSCode" width="14" height="14" className="w-full h-full object-contain" />}>Add to VS Code</Button>
**Manual Installation**
Open a terminal and run the following command:
```sh title="Terminal"
code --add-mcp '{"type":"http","name":"stack-auth","url":"https://mcp.stack-auth.com/"}'
```
Then, from inside VS Code, open the .vscode/mcp.json file and click "Start server".
</TabsContent>
<TabsContent value="claudecode">
Open a terminal and run the following command:
```sh title="Terminal"
claude mcp add --transport http stack-auth https://mcp.stack-auth.com/
```
From within Claude Code, you can use the /mcp command to get more information about the server.
</TabsContent>
<TabsContent value="claudedesktop">
Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector.
Enter the name as stack-auth and the remote MCP server URL as https://mcp.stack-auth.com/.
</TabsContent>
<TabsContent value="windsurf">
Copy the following JSON to your Windsurf MCP config file:
```json title="mcp.json"
{
"mcpServers": {
"stack-auth": {
"serverUrl": "https://mcp.stack-auth.com/"
}
}
}
```
</TabsContent>
<TabsContent value="chatgpt">
<Info>
In Team, Enterprise, and Edu workspaces, only workspace owners and admins have permission to set this.
</Info>
Navigate to **Settings > Connectors**
Add a custom connector with the server URL: `https://mcp.stack-auth.com`
After this, it should be visible in Composer > Deep research Tool.
<Info>
Connectors can only be used with **Deep Research**
</Info>
</TabsContent>
<TabsContent value="gemini">
Add the following JSON to your Gemini CLI configuration file (~/.gemini/settings.json):
```json title="settings.json"
{
"mcpServers": {
"stack-auth": {
"httpUrl": "https://mcp.stack-auth.com/",
"headers": {
"Accept": "application/json, text/event-stream"
}
}
}
}
```
</TabsContent>
</Tabs>
## Markdown Instructions
If you want to include instructions for all clients in your project's README.md file, feel free to copy the following markdown:
<pre className="bg-fd-muted/30 p-4 rounded-lg overflow-x-auto"><code className="text-sm">{`<details name="mcp-install-instructions">
<summary>Cursor</summary>
#### Installation Link
[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=stack-auth&config=eyJ1cmwiOiJodHRwczovL21jcC5zdGFjay1hdXRoLmNvbS8ifQ==)
#### Manual Installation
Add the following to your \`mcp.json\` file:
\`\`\`json
{
"mcpServers": {
"stack-auth": {
"url": "https://mcp.stack-auth.com/"
}
}
}
\`\`\`
</details>
<details name="mcp-install-instructions">
<summary>VSCode</summary>
#### Installation Link
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visual-studio-code&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode:mcp/install?%7B%22type%22%3A%22http%22%2C%22name%22%3A%22stack-auth%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.stack-auth.com%2F%22%7D)
#### Manual Installation
Open a terminal and run the following command:
\`\`\`
code --add-mcp '{"type":"http","name":"stack-auth","url":"https://mcp.stack-auth.com/"}'
\`\`\`
Then, from inside VS Code, open the .vscode/mcp.json file and click "Start server".
</details>
<details name="mcp-install-instructions">
<summary>Claude Code</summary>
Open a terminal and run the following command:
\`\`\`
claude mcp add --transport http stack-auth https://mcp.stack-auth.com/
\`\`\`
From within Claude Code, you can use the \`/mcp\` command to get more information about the server.
</details>
<details name="mcp-install-instructions">
<summary>Claude Desktop</summary>
Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector.
Enter the name as \`stack-auth\` and the remote MCP server URL as \`https://mcp.stack-auth.com/\`.
</details>
<details name="mcp-install-instructions">
<summary>Windsurf</summary>
Copy the following JSON to your Windsurf MCP config file:
\`\`\`json
{
"mcpServers": {
"stack-auth": {
"serverUrl": "https://mcp.stack-auth.com/"
}
}
}
\`\`\`
</details>
<details name="mcp-install-instructions">
<summary>ChatGPT</summary>
*Note: In Team, Enterprise, and Edu workspaces, only workspace owners and admins have permission*
- Navigate to **Settings > Connectors**
- Add a custom connector with the server URL: \`https://mcp.stack-auth.com/\`
- It should then be visible in the Composer > Deep research tool
- You may need to add the server as a source
*Connectors can only be used with **Deep Research***
</details>
<details name="mcp-install-instructions">
<summary>Gemini CLI</summary>
Add the following JSON to your Gemini CLI configuration file (\`~/.gemini/settings.json\`):
\`\`\`json
{
"mcpServers": {
"stack-auth": {
"httpUrl": "https://mcp.stack-auth.com/",
"headers": {
"Accept": "application/json, text/event-stream"
}
}
}
}
\`\`\`
</details>
by [![Hypr MCP](https://hyprmcp.com/hyprmcp_20px.svg)](https://hyprmcp.com/)`}</code></pre>
## Features
The Stack Auth MCP server provides:
- **Authentication Flow Assistance**: Get help implementing sign-in, sign-up, and user management
- **API Documentation**: Access Stack Auth API documentation and examples
- **Code Generation**: Generate boilerplate code for common authentication patterns
- **Best Practices**: Receive guidance on security best practices and implementation patterns

View File

@ -6,40 +6,44 @@ Welcome to Stack Auth, the developer-friendly open-source authentication platfor
You can get started in five minutes with our [setup guide](./getting-started/setup), or jump straight into the documentation.
<CardGroup>
<Card
<QuickLinks>
<QuickLink
title="Setup & Installation"
icon="fa-regular fa-play"
href="./getting-started/setup"
gradient={0}
>
Get started with Stack in 5 minutes
</Card>
</QuickLink>
{/* IF_PLATFORM: react-like */}
<Card
<QuickLink
title="Components"
icon="fa-solid fa-puzzle"
href="./components"
gradient={1}
>
Use our pre-built React components, or create your own
</Card>
</QuickLink>
{/* END_PLATFORM */}
{/* IF_PLATFORM: js-like */}
<Card
<QuickLink
title="SDK Reference"
icon="fa-regular fa-file-lines"
href="./sdk"
gradient={1}
>
Learn how to use Stack Auth's SDK
</Card>
</QuickLink>
{/* END_PLATFORM */}
<Card
<QuickLink
title="REST API Reference"
icon="fa-solid fa-code"
href="/api/overview"
gradient={3}
>
Explore Stack's REST APIs
</Card>
</CardGroup>
</QuickLink>
</QuickLinks>
## Apps

View File

@ -139,7 +139,7 @@ function DocsSidebarLink({
return (
<Link
href={href}
className={`flex items-center gap-2 px-2 py-1.5 rounded-md text-xs transition-colors ${
className={`flex items-center gap-2 px-2 py-1.5 rounded-lg text-xs transition-colors ${
isActive
? 'bg-fd-primary/10 text-fd-primary font-medium'
: 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50'
@ -228,7 +228,7 @@ function ClickableCollapsibleSection({
<div className="group">
<Link
href={href}
className={`flex items-center justify-between w-full px-2 py-1.5 rounded-md text-xs transition-colors ${
className={`flex items-center justify-between w-full px-2 py-1.5 rounded-lg text-xs transition-colors ${
isActive
? 'bg-fd-primary/10 text-fd-primary font-medium'
: 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50'
@ -320,9 +320,34 @@ function renderSidebarContent(tree: PageTree.Root, pathname: string) {
return null;
}
const overviewItem = tree.children.find(
(item) =>
item.type === 'page' &&
(item.url.endsWith('/overview') || item.name === 'Overview')
);
const faqItem = tree.children.find(
(item) =>
item.type === 'page' &&
(item.url.endsWith('/faq') || item.name === 'FAQ')
);
const specialItems = [overviewItem, faqItem].filter(
(item): item is PageTree.Node => !!item
);
const otherItems = tree.children.filter(
(item) => !specialItems.includes(item)
);
return (
<>
{tree.children.map((item, index) => (
{specialItems.length > 0 && (
<div className="mb-4 rounded-xl border border-fd-border/80 bg-fd-muted/10 p-1">
{specialItems.map((item, index) => (
<PageTreeItem key={item.type === 'page' ? item.url : index} item={item} />
))}
</div>
)}
{otherItems.map((item, index) => (
<PageTreeItem key={item.type === 'page' ? item.url : index} item={item} />
))}
</>

View File

@ -50,7 +50,7 @@ export function isInApiSection(pathname: string): boolean {
*/
function isNavLinkActive(pathname: string, navLink: NavLink): boolean {
// More specific matches first
if (navLink.label === 'Welcome' && pathname === '/docs/overview') {
if (navLink.label === 'Welcome' && (pathname === '/docs/overview' || pathname === '/docs/faq')) {
return true;
}
if (navLink.label === 'SDK' && isInSdkSection(pathname)) {
@ -63,7 +63,7 @@ function isNavLinkActive(pathname: string, navLink: NavLink): boolean {
return true;
}
if (navLink.label === 'Guides' && pathname.startsWith('/docs') &&
!isInComponentsSection(pathname) && !isInSdkSection(pathname) && pathname !== '/docs/overview') {
!isInComponentsSection(pathname) && !isInSdkSection(pathname) && pathname !== '/docs/overview' && pathname !== '/docs/faq') {
return true;
}
return false;

View File

@ -109,10 +109,12 @@ export function AppGrid({ appIds, className }: {
className?: string,
}) {
return (
<div className={cn("flex gap-1 lg:gap-8 flex-wrap", className)}>
{appIds.map(appId => (
<AppCard key={appId} appId={appId} />
))}
<div className="max-w-3xl mx-auto">
<div className={cn("flex gap-1 lg:gap-8 flex-wrap justify-center", className)}>
{appIds.map(appId => (
<AppCard key={appId} appId={appId} />
))}
</div>
</div>
);
}

View File

@ -3,6 +3,6 @@ export { CardGroup } from './card-group';
export { DynamicCodeblock } from './dynamic-code-block';
export { Info } from './info';
export { JWTViewer } from './jwt-viewer';
export { QuickLink, QuickLinks } from './quick-links';
export { StackContainer } from './stack-container';

View File

@ -0,0 +1,130 @@
'use client';
import { Code, FileText, Play, Puzzle } from 'lucide-react';
import Link from 'next/link';
import { type ReactNode } from 'react';
import { cn } from '../../lib/cn';
// Icon mapping for common FontAwesome classes to Lucide components
const iconMap: Record<string, React.ComponentType<{ className?: string }>> = {
'fa-regular fa-play': Play,
'fa-solid fa-puzzle': Puzzle,
'fa-regular fa-file-lines': FileText,
'fa-solid fa-code': Code,
};
export type QuickLinkProps = {
/**
* URL for the quick link
*/
href: string,
/**
* Title for the quick link
*/
title: string,
/**
* Optional description
*/
children?: ReactNode,
/**
* Optional FontAwesome icon class (e.g., "fa-solid fa-code") - mapped to Lucide icons
*/
icon?: string,
/**
* Gradient index - not used in current design
*/
gradient?: number,
}
export function QuickLink({
href,
title,
children,
icon,
}: QuickLinkProps) {
const IconComponent = icon ? iconMap[icon] : null;
return (
<Link
href={href}
className={cn(
"group relative block no-underline h-full overflow-hidden",
"rounded-xl border-2 border-fd-border/50 bg-fd-card/50 backdrop-blur-sm",
"transition-all duration-150",
"hover:border-fd-foreground/20 hover:bg-fd-card/80"
)}
>
<div className="relative p-5 flex items-start gap-4">
{/* Icon with floating effect */}
{IconComponent && (
<div className="relative">
<div className={cn(
'relative w-12 h-12 rounded-xl flex items-center justify-center',
'border border-fd-border/50',
'bg-fd-muted/30',
'transition-all duration-150',
'group-hover:scale-110 group-hover:border-fd-primary/30'
)}>
<IconComponent className="w-6 h-6 text-fd-foreground transition-colors duration-150 group-hover:text-fd-primary" />
</div>
</div>
)}
{/* Text content */}
<div className="flex-1 min-w-0">
<div className="font-semibold text-fd-foreground text-base leading-tight mb-1.5 transition-colors duration-150 group-hover:text-fd-primary">
{title}
</div>
{children && (
<div className="text-fd-muted-foreground text-sm leading-tight">
{children}
</div>
)}
</div>
{/* Arrow with slide effect */}
<div className={cn(
"absolute bottom-4 right-4 transition-all duration-150",
"opacity-0 translate-x-2 group-hover:opacity-100 group-hover:translate-x-0",
"text-fd-primary"
)}>
<svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
<path strokeLinecap="round" strokeLinejoin="round" d="M13 7l5 5m0 0l-5 5m5-5H6" />
</svg>
</div>
</div>
</Link>
);
}
export type QuickLinksProps = {
/**
* QuickLink components to display
*/
children: ReactNode,
/**
* Additional CSS classes
*/
className?: string,
}
export function QuickLinks({
children,
className,
}: QuickLinksProps) {
return (
<div
className={cn(
'grid grid-cols-1 md:grid-cols-2 auto-rows-fr gap-4 my-8 not-prose items-stretch max-w-3xl mx-auto',
className
)}
>
{children}
</div>
);
}

View File

@ -7,7 +7,7 @@ export type NavLink = {
}
const DOCS_OVERVIEW_PATH = '/docs/overview';
const DOCS_GUIDES_PATH = '/docs/overview';
const DOCS_GUIDES_PATH = '/docs/getting-started/setup';
const DOCS_SDK_PATH = '/docs/sdk';
const DOCS_COMPONENTS_PATH = '/docs/components';
const API_OVERVIEW_PATH = '/api/overview';

View File

@ -10,7 +10,7 @@ import { EnhancedAPIPage } from './components/api/enhanced-api-page';
import { WebhooksAPIPage } from './components/api/webhooks-api-page';
import AppleSecretGenerator from './components/apple-secret-generator';
import { Card, CardGroup, Info } from './components/mdx';
import { Card, CardGroup, Info, QuickLink, QuickLinks } from './components/mdx';
import ApiSequenceDiagram from './components/mdx/api-sequence-diagram';
import { AuthCard } from './components/mdx/auth-card';
import { DynamicCodeblock } from './components/mdx/dynamic-code-block';
@ -46,6 +46,8 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
//SignIn
Card,
CardGroup,
QuickLink,
QuickLinks,
Info,
SignInStackAuth,
SignInPasswordFirstTab,