Get started with Coderabbit Section UI improvements

[PrasadBhat4]

Get started with Coderabbit Section UI improvements

[linear]

ENG-1968 Get started with Coderabbit Section UI improvements

[traycerai]

Plan

Observations

I've analyzed the CodeRabbit documentation site and identified key issues with the "Getting Started" section. The current structure is fragmented - content in the /docs/getting-started/ folder is scattered across different sidebar sections, creating a disjointed user experience. The sidebar shows "Get started with CodeRabbit" only contains introduction and quickstart, while related content like adding organizations, subscription management, and support are in separate sections. This fragmentation makes it difficult for new users to follow a cohesive onboarding journey.

Approach

The solution focuses on creating a unified, visually appealing "Getting Started" experience by:

1. Restructuring the sidebar to consolidate all getting-started content under one cohesive section
2. Creating a new landing page with an attractive card-based layout that guides users through the onboarding journey
3. Adding visual enhancements like progress indicators, improved typography, and better use of existing design tokens
4. Maintaining consistency with existing Docusaurus patterns while introducing modern UI components

This approach leverages the existing Tailwind CSS setup and design system, ensuring seamless integration with the current site architecture.

Reasoning

I explored the repository structure to understand the Docusaurus setup, examined the current getting-started content, analyzed the sidebar configuration, and reviewed existing UI components and styling patterns. I discovered that the getting-started folder content doesn't align with the sidebar structure, creating a fragmented user experience. The site uses Docusaurus with Tailwind CSS, has a well-established design system with orange branding, and includes custom React components that I can build upon.

Proposed File Changes

📄 sidebars.ts ^(MODIFY) 🔗

Restructure the sidebar to create a unified "Getting Started" section that consolidates all onboarding-related content. Replace the current fragmented structure where getting-started content is scattered across multiple sections. Create a new comprehensive "Getting Started" category that includes:

• Introduction (from overview)
• Quickstart
• Adding Organizations
• Configure CodeRabbit
• Subscription Management
• Upgrading Permissions
• Support

This creates a logical flow for new users and consolidates all onboarding content in one place. Update the category labels and positioning to reflect this new structure while maintaining the existing collapsed/collapsible behavior.

📄 docs/getting-started/index.mdx ^(NEW) 🔗

References

• 📄 docs/getting-started/quickstart.md ^(MODIFY)
• 📄 docs/getting-started/configure-coderabbit.md ^(MODIFY)

Create a new landing page for the Getting Started section that serves as the main entry point. This page will feature:

• A welcoming hero section with clear value proposition
• A card-based layout showcasing the 6 main getting-started topics
• Each card will include an icon, title, description, and estimated time to complete
• Progress tracking visual indicator
• Call-to-action buttons linking to each guide
• Responsive design that works on mobile and desktop

The page will import and use the new GettingStartedCards component and follow MDX patterns similar to existing pages. Set sidebar_position: 0 to make it the first item in the section and include proper front matter for SEO and navigation.

📄 src/components/GettingStartedCards/index.ts ^(NEW) 🔗

References

• 📄 src/components/AiDisclaimer/index.ts

Create a barrel export file for the GettingStartedCards component to enable clean imports in MDX files. Export the main GettingStartedCards component and any related types or utilities. This follows the existing pattern used by other components in the /src/components/ directory like AiDisclaimer.

📄 src/components/GettingStartedCards/GettingStartedCards.tsx ^(NEW) 🔗

References

• 📄 src/components/AiDisclaimer/AiDisclaimer.tsx
• 📄 src/css/custom.css ^(MODIFY)

Create the main React component for the getting started cards layout. The component will:

• Render a responsive grid of cards (2-3 columns on desktop, 1 column on mobile)
• Each card represents one of the 6 getting-started guides
• Include card data with title, description, estimated time, icon, and link
• Use Tailwind CSS classes for styling, following the existing design system
• Implement hover effects and smooth transitions
• Include accessibility features like proper ARIA labels and keyboard navigation
• Use the existing color scheme (orange primary colors) and typography (Poppins/Work Sans)
• Follow React best practices with TypeScript interfaces

The component will be self-contained and reusable, similar to the existing AiDisclaimer component pattern.

📄 src/components/GettingStartedCards/GettingStartedCards.module.css ^(NEW) 🔗

References

• 📄 src/css/custom.css ^(MODIFY)
• 📄 src/pages/index.module.css

Create CSS modules for the GettingStartedCards component to handle component-specific styling that can't be achieved with Tailwind utilities alone. Include:

• Custom card hover animations and transitions
• Gradient backgrounds for cards
• Custom shadows and border effects
• Responsive breakpoint adjustments
• Dark mode specific styling using CSS variables
• Animation keyframes for subtle entrance effects

The CSS will complement Tailwind classes and use the existing CSS custom properties defined in /src/css/custom.css for consistency with the site's design system.

📄 src/components/ProgressIndicator/index.ts ^(NEW) 🔗

Create a barrel export for the ProgressIndicator component that will be used to show user progress through the getting started guides. Export the main component and any related TypeScript interfaces.

📄 src/components/ProgressIndicator/ProgressIndicator.tsx ^(NEW) 🔗

References

• 📄 src/css/custom.css ^(MODIFY)

Create a reusable progress indicator component that can be used across getting started pages to show completion status. The component will:

• Accept props for current step and total steps
• Render a visual progress bar with step indicators
• Show step numbers and completion status
• Use the site's orange color scheme for active/completed states
• Be responsive and accessible
• Include smooth animations for progress changes
• Support both horizontal and compact layouts

This component can be embedded in individual getting started pages to help users track their progress through the onboarding flow.

📄 src/components/ProgressIndicator/ProgressIndicator.module.css ^(NEW) 🔗

References

• 📄 src/css/custom.css ^(MODIFY)

Create CSS modules for the ProgressIndicator component with:

• Progress bar animations and transitions
• Step indicator styling (circles, lines, checkmarks)
• Active, completed, and pending state styles
• Responsive adjustments for mobile devices
• Dark mode compatibility using CSS custom properties
• Smooth transition effects for state changes

The styling will integrate with the existing design system and use the orange color scheme defined in the main CSS file.

📄 docs/getting-started/quickstart.md ^(MODIFY) 🔗

References

• 📄 src/components/ProgressIndicator/index.ts ^(NEW)

Enhance the quickstart guide with improved visual elements:

• Add the ProgressIndicator component at the top to show this is step 1 of 6
• Improve the introduction section with better formatting and visual hierarchy
• Add callout boxes for important information using Docusaurus admonitions
• Include estimated completion time in the front matter
• Add navigation hints to guide users to the next logical step
• Enhance code blocks with better syntax highlighting and copy buttons
• Add visual breaks between major sections

Maintain all existing content while improving the visual presentation and user experience. The page should feel more engaging and easier to follow.

📄 docs/getting-started/configure-coderabbit.md ^(MODIFY) 🔗

References

• 📄 src/components/YamlEditor/YamlEditor.tsx
• 📄 src/components/SchemaViewer.tsx

Enhance the configuration guide with improved visual presentation:

• Add the ProgressIndicator component showing step 2 of 6
• Improve the layout around the existing YamlEditor and SchemaViewer components
• Add better section dividers and visual hierarchy
• Include estimated completion time and difficulty level
• Add navigation elements to guide users to previous/next steps
• Enhance the existing tip callouts with better formatting
• Improve the introduction to make it more welcoming and less technical

Preserve all existing functionality including the interactive YAML editor and schema viewer while making the page more visually appealing and user-friendly.

📄 docs/getting-started/adding-organizations.md ^(MODIFY) 🔗

Enhance the adding organizations guide with visual improvements:

• Add ProgressIndicator component showing step 3 of 6
• Improve the layout and visual hierarchy of the step-by-step instructions
• Enhance the existing screenshots with better captions and context
• Add estimated completion time to front matter
• Include helpful tips and troubleshooting information in callout boxes
• Add navigation elements to connect with other getting started steps
• Improve the "What's next" section with better formatting

Maintain all existing content and screenshots while making the page more visually engaging and easier to follow.

📄 docs/getting-started/subscription-management.md ^(MODIFY) 🔗

Enhance the subscription management guide with improved visual presentation:

• Add ProgressIndicator component showing step 4 of 6
• Improve the organization of the multiple sections (billing, plan changes, seat management)
• Create better visual separation between different management tasks
• Enhance the existing screenshots with improved captions and context
• Add estimated completion times for different tasks
• Include helpful tips in callout boxes
• Improve navigation between sections within the page
• Add better "What's next" guidance

Preserve all existing content and screenshots while making the page more scannable and user-friendly.

📄 docs/getting-started/upgrading-permissions.md ^(MODIFY) 🔗

Enhance the permissions upgrade guide with visual improvements:

• Add ProgressIndicator component showing step 5 of 6
• Improve the step-by-step instructions with better formatting
• Enhance the existing screenshots with better context and captions
• Add troubleshooting tips in callout boxes
• Include estimated completion time in front matter
• Add better explanation of why permission updates are needed
• Improve the list of common reasons for permission updates
• Add navigation elements to connect with other getting started content

Maintain all existing content while making it more visually appealing and easier to understand.

📄 docs/getting-started/support.md ^(MODIFY) 🔗

Enhance the support guide as the final step in the getting started journey:

• Add ProgressIndicator component showing step 6 of 6 (completion)
• Reorganize content with better visual hierarchy
• Enhance the existing screenshots with improved presentation
• Add a "Congratulations" section celebrating completion of getting started
• Improve the Discord and support ticket sections with better formatting
• Add helpful tips for getting the most out of support
• Include a "What's next" section that guides users to advanced features
• Add links back to the getting started overview for reference

Maintain all existing support information while positioning this as the culmination of the onboarding journey.

📄 src/css/custom.css ^(MODIFY) 🔗

Add new CSS custom properties and utility classes to support the enhanced getting started section:

• Add CSS variables for getting started specific colors and spacing
• Include utility classes for card layouts and hover effects
• Add responsive grid utilities that complement Tailwind
• Include animation keyframes for entrance effects and transitions
• Add dark mode support for new UI elements
• Include print-friendly styles for the getting started guides
• Add accessibility improvements for focus states and high contrast mode

Ensure all new styles integrate seamlessly with the existing design system and don't conflict with current styling. Use the existing CSS custom properties pattern for consistency.

Diagram

sequenceDiagram
    participant User
    participant LandingPage as Getting Started Landing
    participant Cards as Card Components
    participant Guides as Individual Guides
    participant Progress as Progress Indicator
    
    User->>LandingPage: Visits /getting-started/
    LandingPage->>Cards: Renders card grid
    Cards->>User: Shows 6 getting started options
    
    User->>Guides: Clicks on Quickstart card
    Guides->>Progress: Shows step 1 of 6
    Progress->>User: Visual progress feedback
    
    User->>Guides: Completes quickstart
    Guides->>User: Shows next step suggestion
    
    User->>Guides: Continues to Configure CodeRabbit
    Guides->>Progress: Shows step 2 of 6
    Progress->>User: Updated progress
    
    Note over User,Progress: Process continues through all 6 steps
    
    User->>Guides: Reaches Support (final step)
    Guides->>Progress: Shows completion (6 of 6)
    Progress->>User: Celebration of completion
    Guides->>User: Suggests advanced features

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end. Make sure you fix all the linting, compilation or validation issues after successful implementation of the plan.

### Observations

I've analyzed the CodeRabbit documentation site and identified key issues with the "Getting Started" section. The current structure is fragmented - content in the `/docs/getting-started/` folder is scattered across different sidebar sections, creating a disjointed user experience. The sidebar shows "Get started with CodeRabbit" only contains introduction and quickstart, while related content like adding organizations, subscription management, and support are in separate sections. This fragmentation makes it difficult for new users to follow a cohesive onboarding journey.

### Approach

The solution focuses on creating a unified, visually appealing "Getting Started" experience by:

1. **Restructuring the sidebar** to consolidate all getting-started content under one cohesive section
2. **Creating a new landing page** with an attractive card-based layout that guides users through the onboarding journey
3. **Adding visual enhancements** like progress indicators, improved typography, and better use of existing design tokens
4. **Maintaining consistency** with existing Docusaurus patterns while introducing modern UI components

This approach leverages the existing Tailwind CSS setup and design system, ensuring seamless integration with the current site architecture.

### Reasoning

I explored the repository structure to understand the Docusaurus setup, examined the current getting-started content, analyzed the sidebar configuration, and reviewed existing UI components and styling patterns. I discovered that the getting-started folder content doesn't align with the sidebar structure, creating a fragmented user experience. The site uses Docusaurus with Tailwind CSS, has a well-established design system with orange branding, and includes custom React components that I can build upon.

## Mermaid Diagram

sequenceDiagram
    participant User
    participant LandingPage as Getting Started Landing
    participant Cards as Card Components
    participant Guides as Individual Guides
    participant Progress as Progress Indicator
    
    User->>LandingPage: Visits /getting-started/
    LandingPage->>Cards: Renders card grid
    Cards->>User: Shows 6 getting started options
    
    User->>Guides: Clicks on Quickstart card
    Guides->>Progress: Shows step 1 of 6
    Progress->>User: Visual progress feedback
    
    User->>Guides: Completes quickstart
    Guides->>User: Shows next step suggestion
    
    User->>Guides: Continues to Configure CodeRabbit
    Guides->>Progress: Shows step 2 of 6
    Progress->>User: Updated progress
    
    Note over User,Progress: Process continues through all 6 steps
    
    User->>Guides: Reaches Support (final step)
    Guides->>Progress: Shows completion (6 of 6)
    Progress->>User: Celebration of completion
    Guides->>User: Suggests advanced features

## Proposed File Changes

### sidebars.ts(MODIFY)

Restructure the sidebar to create a unified "Getting Started" section that consolidates all onboarding-related content. Replace the current fragmented structure where getting-started content is scattered across multiple sections. Create a new comprehensive "Getting Started" category that includes:

- Introduction (from overview)
- Quickstart 
- Adding Organizations
- Configure CodeRabbit
- Subscription Management
- Upgrading Permissions
- Support

This creates a logical flow for new users and consolidates all onboarding content in one place. Update the category labels and positioning to reflect this new structure while maintaining the existing collapsed/collapsible behavior.

### docs/getting-started/index.mdx(NEW)

References: 

- docs/getting-started/quickstart.md(MODIFY)
- docs/getting-started/configure-coderabbit.md(MODIFY)

Create a new landing page for the Getting Started section that serves as the main entry point. This page will feature:

- A welcoming hero section with clear value proposition
- A card-based layout showcasing the 6 main getting-started topics
- Each card will include an icon, title, description, and estimated time to complete
- Progress tracking visual indicator
- Call-to-action buttons linking to each guide
- Responsive design that works on mobile and desktop

The page will import and use the new `GettingStartedCards` component and follow MDX patterns similar to existing pages. Set `sidebar_position: 0` to make it the first item in the section and include proper front matter for SEO and navigation.

### src/components/GettingStartedCards/index.ts(NEW)

References: 

- src/components/AiDisclaimer/index.ts

Create a barrel export file for the GettingStartedCards component to enable clean imports in MDX files. Export the main `GettingStartedCards` component and any related types or utilities. This follows the existing pattern used by other components in the `/src/components/` directory like `AiDisclaimer`.

### src/components/GettingStartedCards/GettingStartedCards.tsx(NEW)

References: 

- src/components/AiDisclaimer/AiDisclaimer.tsx
- src/css/custom.css(MODIFY)

Create the main React component for the getting started cards layout. The component will:

- Render a responsive grid of cards (2-3 columns on desktop, 1 column on mobile)
- Each card represents one of the 6 getting-started guides
- Include card data with title, description, estimated time, icon, and link
- Use Tailwind CSS classes for styling, following the existing design system
- Implement hover effects and smooth transitions
- Include accessibility features like proper ARIA labels and keyboard navigation
- Use the existing color scheme (orange primary colors) and typography (Poppins/Work Sans)
- Follow React best practices with TypeScript interfaces

The component will be self-contained and reusable, similar to the existing `AiDisclaimer` component pattern.

### src/components/GettingStartedCards/GettingStartedCards.module.css(NEW)

References: 

- src/css/custom.css(MODIFY)
- src/pages/index.module.css

Create CSS modules for the GettingStartedCards component to handle component-specific styling that can't be achieved with Tailwind utilities alone. Include:

- Custom card hover animations and transitions
- Gradient backgrounds for cards
- Custom shadows and border effects
- Responsive breakpoint adjustments
- Dark mode specific styling using CSS variables
- Animation keyframes for subtle entrance effects

The CSS will complement Tailwind classes and use the existing CSS custom properties defined in `/src/css/custom.css` for consistency with the site's design system.

### src/components/ProgressIndicator/index.ts(NEW)

Create a barrel export for the ProgressIndicator component that will be used to show user progress through the getting started guides. Export the main component and any related TypeScript interfaces.

### src/components/ProgressIndicator/ProgressIndicator.tsx(NEW)

References: 

- src/css/custom.css(MODIFY)

Create a reusable progress indicator component that can be used across getting started pages to show completion status. The component will:

- Accept props for current step and total steps
- Render a visual progress bar with step indicators
- Show step numbers and completion status
- Use the site's orange color scheme for active/completed states
- Be responsive and accessible
- Include smooth animations for progress changes
- Support both horizontal and compact layouts

This component can be embedded in individual getting started pages to help users track their progress through the onboarding flow.

### src/components/ProgressIndicator/ProgressIndicator.module.css(NEW)

References: 

- src/css/custom.css(MODIFY)

Create CSS modules for the ProgressIndicator component with:

- Progress bar animations and transitions
- Step indicator styling (circles, lines, checkmarks)
- Active, completed, and pending state styles
- Responsive adjustments for mobile devices
- Dark mode compatibility using CSS custom properties
- Smooth transition effects for state changes

The styling will integrate with the existing design system and use the orange color scheme defined in the main CSS file.

### docs/getting-started/quickstart.md(MODIFY)

References: 

- src/components/ProgressIndicator/index.ts(NEW)

Enhance the quickstart guide with improved visual elements:

- Add the ProgressIndicator component at the top to show this is step 1 of 6
- Improve the introduction section with better formatting and visual hierarchy
- Add callout boxes for important information using Docusaurus admonitions
- Include estimated completion time in the front matter
- Add navigation hints to guide users to the next logical step
- Enhance code blocks with better syntax highlighting and copy buttons
- Add visual breaks between major sections

Maintain all existing content while improving the visual presentation and user experience. The page should feel more engaging and easier to follow.

### docs/getting-started/configure-coderabbit.md(MODIFY)

References: 

- src/components/YamlEditor/YamlEditor.tsx
- src/components/SchemaViewer.tsx

Enhance the configuration guide with improved visual presentation:

- Add the ProgressIndicator component showing step 2 of 6
- Improve the layout around the existing YamlEditor and SchemaViewer components
- Add better section dividers and visual hierarchy
- Include estimated completion time and difficulty level
- Add navigation elements to guide users to previous/next steps
- Enhance the existing tip callouts with better formatting
- Improve the introduction to make it more welcoming and less technical

Preserve all existing functionality including the interactive YAML editor and schema viewer while making the page more visually appealing and user-friendly.

### docs/getting-started/adding-organizations.md(MODIFY)

Enhance the adding organizations guide with visual improvements:

- Add ProgressIndicator component showing step 3 of 6
- Improve the layout and visual hierarchy of the step-by-step instructions
- Enhance the existing screenshots with better captions and context
- Add estimated completion time to front matter
- Include helpful tips and troubleshooting information in callout boxes
- Add navigation elements to connect with other getting started steps
- Improve the "What's next" section with better formatting

Maintain all existing content and screenshots while making the page more visually engaging and easier to follow.

### docs/getting-started/subscription-management.md(MODIFY)

Enhance the subscription management guide with improved visual presentation:

- Add ProgressIndicator component showing step 4 of 6
- Improve the organization of the multiple sections (billing, plan changes, seat management)
- Create better visual separation between different management tasks
- Enhance the existing screenshots with improved captions and context
- Add estimated completion times for different tasks
- Include helpful tips in callout boxes
- Improve navigation between sections within the page
- Add better "What's next" guidance

Preserve all existing content and screenshots while making the page more scannable and user-friendly.

### docs/getting-started/upgrading-permissions.md(MODIFY)

Enhance the permissions upgrade guide with visual improvements:

- Add ProgressIndicator component showing step 5 of 6
- Improve the step-by-step instructions with better formatting
- Enhance the existing screenshots with better context and captions
- Add troubleshooting tips in callout boxes
- Include estimated completion time in front matter
- Add better explanation of why permission updates are needed
- Improve the list of common reasons for permission updates
- Add navigation elements to connect with other getting started content

Maintain all existing content while making it more visually appealing and easier to understand.

### docs/getting-started/support.md(MODIFY)

Enhance the support guide as the final step in the getting started journey:

- Add ProgressIndicator component showing step 6 of 6 (completion)
- Reorganize content with better visual hierarchy
- Enhance the existing screenshots with improved presentation
- Add a "Congratulations" section celebrating completion of getting started
- Improve the Discord and support ticket sections with better formatting
- Add helpful tips for getting the most out of support
- Include a "What's next" section that guides users to advanced features
- Add links back to the getting started overview for reference

Maintain all existing support information while positioning this as the culmination of the onboarding journey.

### src/css/custom.css(MODIFY)

Add new CSS custom properties and utility classes to support the enhanced getting started section:

- Add CSS variables for getting started specific colors and spacing
- Include utility classes for card layouts and hover effects
- Add responsive grid utilities that complement Tailwind
- Include animation keyframes for entrance effects and transitions
- Add dark mode support for new UI elements
- Include print-friendly styles for the getting started guides
- Add accessibility improvements for focus states and high contrast mode

Ensure all new styles integrate seamlessly with the existing design system and don't conflict with current styling. Use the existing CSS custom properties pattern for consistency.

---

Developer Humor

🎯 Why did the getting started guide go to therapy?
Because it had too many scattered thoughts!
Now it's all organized and ready to help users
Navigate their CodeRabbit journey with style! ✨

   📚 ➜ 🎨 ➜ 🚀
  Docs   UI   Success!

---

Execution Information

Branch: main
Commit: 1b47d99

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.