docs: add comprehensive documentation pages#981
Conversation
Add 10 new documentation pages covering core Superset features: - First workspace setup guide - Diff viewer and git workflow - Parallel workspaces for concurrent development - Terminal integration features - Agent integration (Claude Code, Codex) - Workspaces and branches relationship - Environment variables reference - IDE integration (Cursor/VS Code) - Monorepo support guide - FAQ and known issues Also includes CONTENT-REVIEW.md tracking image placeholders and features needing verification.
📝 WalkthroughWalkthroughThis PR reorganizes documentation structure by removing the generic core-features page, adding eleven focused feature documentation pages (agents, diff-viewer, monorepos, terminals, workspaces, ports, IDE integration, keyboard shortcuts, customization, FAQ), restructuring sidebar navigation with Help and Guides sections, simplifying existing guides, and moving the ports documentation from marketing to docs site. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
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 |
🧹 Preview Cleanup CompleteThe following preview resources have been cleaned up:
Thank you for your contribution! 🎉 |
The sidebar was hardcoded in SidebarContent.tsx and not reading from meta.json. Added all new pages to the sidebar sections and added Help section with FAQ.
- Created placeholder.svg for visual consistency - Added images with TODO comments for future replacement - All pages now have proper image placeholders
Updated overview, core-features, installation, quick-start, and setup-teardown-scripts with placeholder images and improved content structure with cross-links to new pages.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@apps/docs/content/docs/agent-integration.mdx`:
- Around line 26-28: Replace the incorrect single-command usage "claude /login"
in the docs with the two-step authentication flow: instruct users to run
`claude` to start the interactive session and then enter `/login` at the claude
prompt; update both occurrences of the exact string "claude /login" (including
the troubleshooting line that currently repeats it) to this multi-step
instruction and keep the npm package name `@anthropic-ai/claude-code` unchanged.
In `@apps/docs/content/docs/faq.mdx`:
- Around line 46-49: The FAQ entry titled "Do terminal sessions persist after
closing Superset?" currently states persistence as a blanket fact; update the
paragraph to clarify that terminal session persistence is conditional on the
terminal persistence setting (enabled by default) and that if persistence is
disabled sessions will not survive app restarts—either mention the toggle
explicitly or rephrase to say sessions survive restarts only when the
persistence setting is enabled. Reference the existing FAQ heading text to
locate and replace the current two-sentence answer accordingly.
In `@apps/docs/content/docs/parallel-workspaces.mdx`:
- Around line 29-34: Update the wording in the "Superset uses [git worktrees]"
section to clarify that worktrees provide isolated working directories but share
the Git object store rather than creating full disk copies: replace the bullet
"Each workspace has a complete, isolated copy of your codebase" with something
like "Each workspace has an isolated working directory but shares Git objects
(the object store) with the repository, so it’s not a full duplicate on disk";
keep the rest of the bullets but ensure disk-usage implications are clear.
In `@apps/docs/content/docs/use-with-cursor.mdx`:
- Around line 41-46: Update the window.title snippet to include a brief caveat
about VS Code version and Cursor layout: mention that
`${activeRepositoryBranchName}` and related variables are available in VS Code
1.87+ and that Cursor’s Agent layout does not honor `window.title` (only the
Editor layout does); add a short sentence pointing readers to the VS Code
Settings Editor for the authoritative list of variables (link to settings
editor). Ensure the tokens `${activeRepositoryBranchName}`, `${separator}`,
`${rootName}`, and `${profileName}` are referenced in the note so users see
which variables have version/layout constraints.
🧹 Nitpick comments (10)
apps/docs/content/docs/workspaces-and-branches.mdx (1)
1-126: Well-structured documentation page.The content is comprehensive, covering the workspace-branch relationship clearly with practical examples and best practices. The TODO placeholders for images are appropriately placed.
One minor typo on line 113:
📝 Suggested fix
-# Delete local branch (after checkout another branch) +# Delete local branch (after checking out another branch)apps/docs/content/docs/terminal-integration.mdx (2)
36-45: Keyboard shortcuts are macOS-only.The shortcuts table only shows macOS key combinations (⌘). Consider adding Windows/Linux alternatives (Ctrl) for cross-platform users, or note that these are macOS shortcuts.
Action macOS Windows/Linux New terminal tab ⌘T Ctrl+T Close terminal tab ⌘W Ctrl+W ... ... ...
129-137: Inconsistent shortcut notation.Earlier sections use macOS-style shortcuts (⌘K, ⌘T), but this section uses
Ctrl+R. For consistency, either use the same notation throughout or explicitly label platform-specific shortcuts.apps/docs/content/docs/first-workspace.mdx (2)
46-48: Reference to "Claude instances" may be too specific.Line 47 mentions "multiple Claude instances" but the agent-integration page supports multiple AI agents (Claude Code, Codex, OpenCode). Consider generalizing to "AI agent instances" for consistency.
📝 Suggested fix
-- Explore [parallel workspaces](/docs/parallel-workspaces) to run multiple Claude instances +- Explore [parallel workspaces](/docs/parallel-workspaces) to run multiple AI agent instances
24-25: Keyboard shortcuts are macOS-only.Same as other documentation pages - consider adding Windows/Linux alternatives or noting these are macOS shortcuts.
apps/docs/CONTENT-REVIEW.md (3)
6-7: Bare URL should use Markdown link syntax.Per markdownlint, use proper Markdown link syntax instead of bare URLs.
📝 Suggested fix
-- **Source**: Conductor documentation (https://docs.conductor.build/) +- **Source**: [Conductor documentation](https://docs.conductor.build/)
15-39: Add blank lines around tables for proper Markdown rendering.Per markdownlint (MD058), tables should be surrounded by blank lines for consistent rendering across Markdown parsers.
📝 Suggested fix (example for first table)
### Get Started Section + | Page | Status | Needs Review | |------|--------|--------------| | `first-workspace.mdx` | ✅ Created | Verify workflow matches Superset UX | + ### Core Features SectionApply similarly to other tables in this file.
180-204: Add language identifier to fenced code block.Per markdownlint (MD040), fenced code blocks should specify a language for syntax highlighting.
📝 Suggested fix
-``` +```text Get Started ├── quick-startapps/docs/content/docs/using-monorepos.mdx (1)
156-164: Troubleshooting is bun-specific.The lockfile removal example uses
bun.lockb. Consider noting alternatives for users who might use npm or yarn:📝 Suggested enhancement
### Outdated dependencies in workspace If your workspace has stale dependencies: ```bash rm -rf node_modules -rm bun.lockb +rm bun.lockb # or package-lock.json / yarn.lock bun install</details> </blockquote></details> <details> <summary>apps/docs/src/app/(docs)/components/Sidebar/components/SidebarContent/SidebarContent.tsx (1)</summary><blockquote> `74-88`: **Extract a shared icon size constant to avoid magic numbers.** The new icon repeats the same hardcoded `1.4em` size used across the other SVGs. Consider hoisting a single `ICON_SIZE` constant and reusing it for consistency and maintainability. As per coding guidelines, avoid magic numbers. <details> <summary>♻️ Proposed refactor</summary> ```diff +const ICON_SIZE = "1.4em"; const GetStartedIcon = () => ( <svg xmlns="http://www.w3.org/2000/svg" - width="1.4em" - height="1.4em" + width={ICON_SIZE} + height={ICON_SIZE} viewBox="0 0 24 24" role="img" aria-label="Get Started" > @@ const CoreFeaturesIcon = () => ( <svg xmlns="http://www.w3.org/2000/svg" - width="1.4em" - height="1.4em" + width={ICON_SIZE} + height={ICON_SIZE} viewBox="0 0 24 24" role="img" aria-label="Core Features" > @@ const GuidesIcon = () => ( <svg xmlns="http://www.w3.org/2000/svg" - width="1.4em" - height="1.4em" + width={ICON_SIZE} + height={ICON_SIZE} viewBox="0 0 24 24" role="img" aria-label="Guides" > @@ const HelpIcon = () => ( <svg xmlns="http://www.w3.org/2000/svg" - width="1.4em" - height="1.4em" + width={ICON_SIZE} + height={ICON_SIZE} viewBox="0 0 24 24" role="img" aria-label="Help" >
| 1. Install Claude Code: Follow the [official setup guide](https://docs.anthropic.com/en/docs/claude-code) | ||
| 2. Authenticate: Run `claude /login` in your terminal | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Claude Code CLI login command authentication official documentation
💡 Result:
In the official Anthropic documentation for Claude Code:
-
Interactive CLI login command: start Claude Code, then run
/logininside the interactive session:claude # then at the Claude Code prompt: /loginThis signs you in via either a Claude.ai account (recommended) or an Anthropic Console account, and the CLI stores credentials so you don’t need to log in every time. [1]
-
Non-interactive / SDK-style authentication: set an Anthropic API key in the environment as
ANTHROPIC_API_KEY. [3] -
General CLI command reference: Anthropic’s CLI reference documents the
claudecommand and related flags (login itself is handled in-session via/loginas shown above). [2]
Sources (official): Quickstart (login) [1], CLI reference [2], Claude Code SDK (authentication) [3].
🏁 Script executed:
# Search for any references to claude-code or anthropic packages in the repo
fd -t f "package.json\|README\|\.md" | head -20Repository: superset-sh/superset
Length of output: 46
🏁 Script executed:
# Look for any Claude Code documentation or references in the docs
find . -type f \( -name "*.mdx" -o -name "*.md" \) -exec rg -l "Claude Code\|claude /login\|@anthropic-ai/claude-code" {} \;Repository: superset-sh/superset
Length of output: 46
🏁 Script executed:
# Try to locate and examine the actual content at the specified lines
fd -t f "agent-integration.mdx" 2>/dev/null | head -5Repository: superset-sh/superset
Length of output: 108
🏁 Script executed:
# Search more broadly for any documentation files with agent or integration
fd -t f "\.mdx$\|\.md$" | rg -i "agent|integration" 2>/dev/nullRepository: superset-sh/superset
Length of output: 46
🏁 Script executed:
# Look for the specific file mentioned in the review
find . -name "agent-integration.mdx" -o -name "*agent*integration*" 2>/dev/null | head -10Repository: superset-sh/superset
Length of output: 110
🏁 Script executed:
# Read the agent-integration.mdx file to check lines 26-28 and 133-138
cat -n ./apps/docs/content/docs/agent-integration.mdx | sed -n '20,40p; 128,145p'Repository: superset-sh/superset
Length of output: 1016
🏁 Script executed:
# Let me verify the exact format by checking if there are any other references in the docs
grep -n "claude" ./apps/docs/content/docs/agent-integration.mdxRepository: superset-sh/superset
Length of output: 516
🏁 Script executed:
# Check if line 149 is in a different context or shows the same error repeated
cat -n ./apps/docs/content/docs/agent-integration.mdx | sed -n '145,155p'Repository: superset-sh/superset
Length of output: 277
Correct the Claude Code authentication command format in two locations.
According to official Anthropic documentation, the authentication flow is: run claude to start the interactive session, then execute /login at the prompt—not as a single command claude /login. This command format will fail for users.
Update lines 28 and 149:
- Line 28: Change
claude /loginto multi-step instructions (startclaude, then/login) - Line 149 (troubleshooting section): Same fix needed
The npm package name @anthropic-ai/claude-code is correct.
🤖 Prompt for AI Agents
In `@apps/docs/content/docs/agent-integration.mdx` around lines 26 - 28, Replace
the incorrect single-command usage "claude /login" in the docs with the two-step
authentication flow: instruct users to run `claude` to start the interactive
session and then enter `/login` at the claude prompt; update both occurrences of
the exact string "claude /login" (including the troubleshooting line that
currently repeats it) to this multi-step instruction and keep the npm package
name `@anthropic-ai/claude-code` unchanged.
| ### For Cursor / VS Code | ||
|
|
||
| 1. Open User Settings with **⌘⇧P** and search "Preferences: Open User Settings" | ||
| 2. Search for `window.title` | ||
| 3. Set it to: `${activeRepositoryBranchName}${separator}${rootName}${separator}${profileName}` | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
VS Code window.title configuration supported variables documentation official
💡 Result:
Official VS Code docs don’t maintain a separate web page that lists all window.title template variables in one place; instead they point you to the setting’s own inline documentation in the Settings UI / defaultSettings.json.
Where to find the official list:
-
Variables Reference (official docs)
Notes that only “select settings” support substitution, and explicitly calls outwindow.titleas having its own variables, recommending you refer to the Settings editor comments for setting-specific variables. [1] -
Default Settings reference (official docs)
Explains how to open Preferences: Open Default Settings (JSON), which showsdefaultSettings.json(read-only). That file contains thewindow.titlesetting with the authoritative comment block listing the supported variables. [2] -
Release notes for added variables (official docs)
VS Code 1.87 (February 2024) added${activeRepositoryName}and${activeRepositoryBranchName}for use inwindow.title. [3]
Sources: [1] [2] [3]
🌐 Web query:
${rootName} ${profileName} VS Code window.title variable
💡 Result:
In VS Code’s window.title setting, these placeholders mean:
${rootName}: The workspace name (folder/workspace), including optional suffixes like the remote name ([SSH]) and “(Workspace)” when applicable. [1]${profileName}: The profile name the window is using (typically shown likeMy Profile (Profile)), and it’s omitted/ignored when using the Default Profile. [1][2]
Example (from VS Code docs) showing how they’re commonly used together:
"window.title": "${dirty}${activeEditorShort}${separator}${rootName}${separator}${profileName}${separator}${appName}"[3]
Sources: [1] [2] [3]
🌐 Web query:
${separator} VS Code window.title variable meaning
💡 Result:
In VS Code’s "window.title" setting, ${separator} is a conditional delimiter used to split title segments (e.g., file name | workspace | app name). It only appears when the text/variables on both sides resolve to something non-empty, so you don’t end up with leading/trailing separators. [3]
What character/string it inserts is controlled by "window.titleSeparator" (the separator used by window.title). [1]
Example:
"window.title": "${activeEditorShort}${separator}${rootName}${separator}${appName}",
"window.titleSeparator": " - "[1][3]
🌐 Web query:
Cursor editor window.title configuration tokens support
💡 Result:
Cursor inherits VS Code’s window.title templating, so the same ${...} variables/tokens are intended to work (for example ${dirty}, ${activeEditorShort|Medium|Long}, ${rootName}, ${appName}, ${separator}, etc.). VS Code documents the defaults and explicitly calls out ${separator} and ${activeEditorLong} (full path) as part of the window.title system. [1]
Cursor-specific limitation: as of late Dec 2025 / Jan 2026, Cursor staff state that window.title customization is only applied in the “Editor” layout/mode; the “Agent” layout uses fixed title logic (workspace name / ${rootName}) and does not apply window.title. [2], [3]
So: tokens are supported (VS Code-style), but only when Cursor is in Editor mode; Agent layout ignores them. [2], [3]
Sources:
[1] https://code.visualstudio.com/updates/v1_10
[2] https://forum.cursor.com/t/custom-titlebar-ignores-window-title-setting/145945
[3] https://forum.cursor.com/t/agent-layout-does-not-respect-the-window-title/147359
Add version and Cursor layout caveats to the window.title configuration.
The tokens (${activeRepositoryBranchName}, ${separator}, ${rootName}, ${profileName}) are valid VS Code variables (added in 1.87+), but the snippet lacks critical context: Cursor's Agent layout does not apply window.title settings (only Editor layout respects them), and users on older VS Code versions lack ${activeRepositoryBranchName}. Consider adding a brief note clarifying supported editor versions and Cursor layout requirements, with a link to the VS Code settings editor for the authoritative variable list.
💡 Suggested wording tweak
3. Set it to: `${activeRepositoryBranchName}${separator}${rootName}${separator}${profileName}`
+ (Cursor applies this only in Editor layout; Agent layout uses fixed titles. Requires VS Code 1.87+ for `activeRepositoryBranchName`.)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### For Cursor / VS Code | |
| 1. Open User Settings with **⌘⇧P** and search "Preferences: Open User Settings" | |
| 2. Search for `window.title` | |
| 3. Set it to: `${activeRepositoryBranchName}${separator}${rootName}${separator}${profileName}` | |
| ### For Cursor / VS Code | |
| 1. Open User Settings with **⌘⇧P** and search "Preferences: Open User Settings" | |
| 2. Search for `window.title` | |
| 3. Set it to: `${activeRepositoryBranchName}${separator}${rootName}${separator}${profileName}` | |
| (Cursor applies this only in Editor layout; Agent layout uses fixed titles. Requires VS Code 1.87+ for `activeRepositoryBranchName`.) | |
🤖 Prompt for AI Agents
In `@apps/docs/content/docs/use-with-cursor.mdx` around lines 41 - 46, Update the
window.title snippet to include a brief caveat about VS Code version and Cursor
layout: mention that `${activeRepositoryBranchName}` and related variables are
available in VS Code 1.87+ and that Cursor’s Agent layout does not honor
`window.title` (only the Editor layout does); add a short sentence pointing
readers to the VS Code Settings Editor for the authoritative list of variables
(link to settings editor). Ensure the tokens `${activeRepositoryBranchName}`,
`${separator}`, `${rootName}`, and `${profileName}` are referenced in the note
so users see which variables have version/layout constraints.
- Remove redundant pages: core-features.mdx, environment-variables.mdx - Shorten all pages significantly (1526 → 445 lines, 70% reduction) - Update sidebar and navigation - Keep content clean and scannable
…le workspaces page
1 participant
Summary
meta.jsonto organize docs into logical sectionsCONTENT-REVIEW.mdtracking image placeholders and content needing verificationNew Pages
first-workspace.mdxdiff-viewer.mdxparallel-workspaces.mdxterminal-integration.mdxagent-integration.mdxworkspaces-and-branches.mdxenvironment-variables.mdxuse-with-cursor.mdxusing-monorepos.mdxfaq.mdxNavigation Structure
Test plan
bun run buildin apps/docsCONTENT-REVIEW.mdfor content needing verificationSummary by CodeRabbit
Release Notes
Documentation
UI
Removals
✏️ Tip: You can customize this high-level summary in your review settings.