Starlight Components Demo

This page demonstrates every Starlight MDX component and formatting convention used throughout the Developer Toolkit documentation. Use it as a reference when writing or editing articles.

Aside Variants

Asides highlight important information. Each variant signals a different intent.

Note

Use note for supplementary context the reader should be aware of but can skip without losing the main thread. Example: “Model availability and pricing change frequently. Verify current pricing before making decisions.”

Tip

Use tip for copy-paste prompts and actionable advice. Example prompt:

Review this file for security vulnerabilities. Focus on SQL injection, XSS, and authentication bypass. Ignore style issues.

Every workflow article includes at least 2-3 tip asides with ready-to-use prompts.

Caution

Use caution for common pitfalls and “gotchas” that trip up developers. Example: “Do not run --dangerously-skip-permissions outside of CI/CD environments. It bypasses all safety checks.”

Danger

Use danger for irreversible actions or security-critical warnings. Example: “Never commit API keys or secrets to version control. Use environment variables and .env files excluded via .gitignore.”

Tabs for Three-Tool Comparisons

The core pattern across Developer Toolkit. Every shared workflow uses three tabs.

Cursor

Cursor is an IDE-first tool. Workflows happen inside the editor with visual feedback.

Cmd/Ctrl+I    Open Agent chat
Cmd/Ctrl+K    Inline edit
Tab           Accept autocomplete
@file.ts      Reference a file

Key features: Tab autocomplete, Background Agent, BugBot, checkpoints, visual diffs.

Claude Code

Claude Code is a CLI-first tool. Workflows happen in the terminal with text-based interaction.

claude                    # Start interactive session
claude -p "fix the bug"   # One-off query
/compact                  # Summarize conversation
@file.ts                  # Reference a file

Key features: Hooks, custom slash commands, headless mode, piping, session management.

Codex

Codex is a multi-surface tool. Workflows span the App, CLI, IDE extension, and Cloud agents.

codex                              # Start interactive session
codex "implement the feature"      # Start with prompt
codex --full-auto                  # Autonomous mode

Key features: Git worktrees, GitHub/Slack/Linear automations, cloud agents, approval modes.

Nested Tabs

Tabs can be nested for sub-comparisons within a tool section:

By Task

Task	Recommended Model
Complex architecture	Claude Opus 4.6
Everyday coding	Claude Sonnet 4.5
Speed-critical iteration	Cursor Composer 1
Bug fixing in Cursor	GPT-5.2
All Codex workflows	GPT-5.3-Codex

By Budget

Budget	Primary Model
Premium	Claude Opus 4.6
Standard	Claude Sonnet 4.5
Cost-sensitive	GPT-5.2

Code Blocks

Syntax Highlighting with Title

src/lib/auth.ts

interface AuthResult {
  success: boolean;
  user?: User;
  error?: string;
}

export async function authenticateUser(
  token: string
): Promise<AuthResult> {
  try {
    const payload = await verifyJWT(token);
    const user = await db.users.findById(payload.sub);
    return { success: true, user };
  } catch (error) {
    return { success: false, error: "Invalid token" };
  }
}

Line Highlighting and Diff Markers

config.js

// Configuration update
const config = {
  port: process.env.PORT || 3000,
  database: process.env.DATABASE_URL,
  cacheEnabled: true,       // Added: enable caching
  // debugMode: true,       // Removed: disable debug in production
};

Shell Commands

# Install dependencies
npm install @anthropic-ai/claude-code
claude --version

# Initialize project configuration
claude
/init

Multi-Language Examples

TypeScript

const users = await db
  .select()
  .from(usersTable)
  .where(eq(usersTable.role, "admin"));

Python

users = await db.execute(
    select(users_table).where(
        users_table.c.role == "admin"
    )
)

Go

var users []User
err := db.Where("role = ?", "admin").Find(&users).Error

Cards and Card Grids

Single Cards

Key Concept

Cards work well for self-contained explanations, definitions, or callouts that deserve visual separation from the main text flow.

Card Grids

Cursor

IDE-first development with visual editing, agent mode, tab autocomplete, and background agents.

Claude Code

CLI-first development with terminal workflows, hooks, custom commands, and headless CI integration.

Codex

Multi-surface development spanning App, CLI, IDE, and Cloud with automations and worktrees.

Link Cards

Keyboard Shortcuts Complete shortcut tables for all three tools

Command Reference Every CLI command, slash command, and context symbol

Steps Component

Steps render a numbered procedural walkthrough. The component expects a single ordered list.

1. Install the tool

   Choose your preferred AI coding tool and install it following the quick-start guide.

2. Configure project context

   Create the configuration file (.cursor/rules/, CLAUDE.md, or AGENTS.md) with your project’s tech stack, coding standards, and common commands.

3. Set up MCP servers

   Install MCP servers for your external tools (database, browser, Git hosting) to give the AI direct access.

4. Start with a real task

   Pick a low-risk task from your backlog — a bug fix, a test, or a small feature. Work through it with the AI and iterate on your prompts.

5. Review and refine

   After your first session, update your configuration file based on what worked and what the AI got wrong. The configuration improves with every session.

File Tree

• Directorysrc/

  • Directorycomponents/

    • Header.astro
    • Footer.astro
    • PaywallModal.tsx
  • Directorycontent/

    • Directorydocs/

      • Directoryen/

        • Directoryintroduction/

          • …
        • Directorycursor-ide/

          • …
        • Directoryclaude-code/

          • …
        • Directorycodex/

          • …
        • Directoryshared-workflows/

          • …
        • Directoryappendices/

          • …
        • Directoryresources/

          • …
      • Directorypl/

        • …
  • Directorylib/

    • Directorydb/

      • schema.ts
      • queries.ts
    • auth.ts
  • Directorypages/

    • Directoryapi/

      • Directorysubscription/

        • …
      • Directoryauth/

        • …
    • index.astro
• CLAUDE.md
• Directory.cursor/

  • Directoryrules/

    • project.mdc
• AGENTS.md
• package.json
• astro.config.mjs

Tables

Simple Table

Feature	Cursor	Claude Code	Codex
Tab autocomplete	Yes	No	No
Background agents	Yes	Yes (headless)	Yes (Cloud)
MCP servers	Yes	Yes	Yes
Git integration	Built-in	Via tools	Via worktrees
Custom commands	Extensions	.claude/commands/	Slash commands

Detailed Comparison Table

Model	Provider	Context	Input $/1M	Output $/1M	Best For
Claude Opus 4.6	Anthropic	200K	$5	$25	Complex architecture
Claude Sonnet 4.5	Anthropic	1M	$3	$15	Everyday coding
GPT-5.3-Codex	OpenAI	200K+	Subscription	Subscription	Codex workflows
GPT-5.2	OpenAI	200K+	$1.25	$10	Bug fixing
Gemini 3 Pro	Google	1M	$2	$12	Multimodal analysis

Badges

Badges add inline status indicators:

• New — New features or recently added content
• Updated — Recently updated sections
• Deprecated — Features being phased out
• Breaking — Breaking changes that require action
• Stable — Production-ready features

Collapsible Details

Advanced: Combining MCP servers with custom commands

You can create custom slash commands in Claude Code that leverage MCP servers for multi-step workflows:

---
allowed-tools: [Read, Edit, Bash, mcp__github__create_pull_request]
description: Create a PR from the current changes
---

1. Run: !git diff --stat
2. Summarize the changes
3. Create a PR with a descriptive title and body
4. Report the PR URL

This pattern works because MCP tools are available as allowed-tools in custom command definitions.

Advanced: Cursor rules with agent-selected activation

When you omit both alwaysApply and globs, the rule becomes “agent-selected.” Cursor reads the description field and decides whether the rule is relevant to the current task:

---
description: "Database migration patterns using Drizzle ORM. Use when creating or modifying database schemas."
---

## Migration Rules
- Always create a new migration file, never modify existing ones
- Run `npm run db:migrate` after creating migrations
- Test migrations with `npm run db:migrate:dry`

This is useful for specialized rules that only apply to certain types of tasks.

Markdown Formatting

Inline Code and Keyboard Shortcuts

Reference commands like /compact, files like CLAUDE.md, and keyboard shortcuts like Cmd+I using inline code formatting.

Blockquotes for Prompts

When showing a prompt the user should type or paste:

Review this authentication middleware for security vulnerabilities. Check for: JWT validation issues, missing rate limiting, CSRF protection gaps, and session fixation risks. Suggest fixes with code.

Lists

Unordered lists for feature sets and options:

• MCP servers provide persistent tool connections
• Agent Skills offer lightweight, shareable capabilities
• Custom commands create reusable workflows
• Hooks intercept and modify AI behavior at specific points

Ordered lists for sequential procedures:

1. Read the error message carefully
2. Check the relevant log file
3. Search the codebase for the failing function
4. Ask the AI to explain the failure mode
5. Implement and test the fix

Article Structure Reference

Every article in Developer Toolkit (except index pages) follows this structure:

Standard Article Anatomy

1. Problem Hook (2-3 sentences) — A scenario the reader recognizes from real work
2. What You Will Walk Away With — Bullet list of concrete outcomes
3. The Workflow — Step-by-step with real prompts and tool interactions
4. Copy-Paste Prompts — Ready-to-use prompts in <Aside type="tip"> blocks
5. When This Breaks — Common failure modes and recovery strategies
6. What is Next — Links to related articles

This structure ensures every article delivers immediate, actionable value rather than abstract theory.