chore(theme): better UI for overview items without headers case

[Copilot]

Plan to Improve Overview Section Formatting

• Understand the issue: When Overview pages only contain a title without h2/h3 subheadings, the OverviewGroup component displays cards with empty content sections, which looks unappealing
• Analyze the OverviewGroup component to understand the rendering logic
• Implement grid layout for items without headers or custom items
• Update the OverviewGroup component styling for grid layout
• Update E2E test fixtures and test expectations
• Test the changes by building and viewing the documentation site
• Run E2E tests to validate changes
• Fix CI lint errors (heading case)
• Complete implementation

Summary

This PR improves the aesthetics of Overview pages by implementing different layouts based on whether items have subheadings:

Changes

Items WITH headers (h2/h3): Display in standard split layout with title on left, headers on right
Items WITHOUT headers: Display in responsive grid layout (simple cards)

Technical Details

1. packages/core/src/theme/components/OverviewGroup/index.tsx:

   • Separated items into two groups: with content and without content
   • Items with content render in standard split layout
   • Items without content render in new grid layout

2. packages/core/src/theme/components/OverviewGroup/index.scss:

   • Added .rp-overview-group__grid for responsive grid (4/3/2/1 columns)
   • Added .rp-overview-group__grid-item for grid card styling

3. E2E tests: Updated to check for items in both layouts

4. Lint fixes: Corrected heading case in test fixtures to pass CI checks

Screenshots

Built-in Hooks (items without headers display in clean grid layout):

API Overview (items with headers display in standard split layout):

Original prompt

implement this.

[Chronological Review: The conversation began with the user expressing a concern about the appearance of the Overview section in their documentation, specifically when it only contains a title without any subheadings (h2, h3). The user requested an implementation to address this issue, indicating a desire for improved aesthetics in the documentation layout.]

[Intent Mapping:

• User Request 1: "当 Overview 仅含标题，而没有 h2 h3 的时候会比较丑，如图 1" - The user wants to improve the visual presentation of the Overview section in their documentation.
• User Request 2: "implement this." - The user is asking for the implementation of the requested change.]

[Technical Inventory:

• Repository: rspress
• Current Branch: syt/docs-polish
• Active Pull Request: docs: add components (docs: add components #2891)
• File in Focus: /Users/bytedance/Documents/codes/rspress/website/docs/en/ui/runtime-components/head.mdx]

[Code Archaeology:

• The specific file being worked on is head.mdx, which likely contains the documentation structure that needs modification to enhance the Overview section's appearance.]

[Progress Assessment:

• Completed Tasks: The user has identified the issue with the Overview section's appearance.
• Partially Complete Work: The implementation of the requested visual improvements is pending.]

[Context Validation: The user’s request for implementation is clear, and the context of the file being modified is captured.]

[Recent Commands Analysis:

• Last Agent Commands: The user requested an implementation of the visual improvement for the Overview section.
• Tool Results Summary: No specific tool results were returned as the conversation focused on user requests rather than tool executions.
• Pre-Summary State: The agent was actively discussing the implementation of the requested changes to the documentation layout when the token budget was exceeded.
• Operation Context: The commands were executed in response to the user's request for improving the aesthetics of the documentation, aligning with their goal of enhancing the user interface.]

1. Conversation Overview: - Primary Objectives: The user requested improvements to the Overview section of their documentation, stating, "当 Overview 仅含标题，而没有 h2 h3 的时候会比较丑，如图 1" and subsequently asked to "implement this." - Session Context: The conversation focused on addressing a specific aesthetic issue in the documentation layout, particularly regarding the Overview section's formatting. - User Intent Evolution: The user clearly articulated their need for a more visually appealing documentation structure and requested implementation of the changes.

2. Technical Foundation:

• Repository: rspress
• Current Branch: syt/docs-polish
• Active Pull Request: docs: add components (docs: add components #2891)

3. Codebase Status:

• File Name: head.mdx
• Purpose: This file is part of the documentation structure that requires modification to improve the Overview section's appearance.
• Current State: The user has identified the need for changes but has not yet implemented them.
• Key Code Segments: Specific code segments were not discussed, but the focus is on the layout of the Overview section.
• Dependencies: The changes will likely affect how the documentation is rendered and viewed by users.

4. Problem Resolution:

• Issues Encountered: The user identified that the Overview section looks unappealing without subheadings.
• Solutions Implemented: No solutions have been implemented yet; the user is awaiting the implementation of their request.
• Debugging Context: There are no ongoing troubleshooting efforts mentioned.
• Lessons Learned: The importance of visual presentation in documentation has been highlighted.

5. Progress Tracking:

• Completed Tasks: The user has articulated the problem with the Overview section.
• Partially Complete Work: The implementation of the requested changes is still pending.
• Validated Outcomes: No features or code have been confirmed working through testing yet.

6. Active Work State:

• Current Focus: The user is focused on implementing visual improvements to the Overview section of the documentation.
• Recent Context: The last few exchanges involved the user expressing their concerns about the documentation layout and requesting implementation.
• Working Code: No specific code snippets were discussed recently.
• Immediate Context: The user was addressing the aesthetic issue of the Overview section before the summary was triggered.

7. Recent Operations:

• Last Agent Commands: The user requested to "implement this" regarding the visual improvements for the Overview section.
• Tool Results Summary: No specific tool results were generated as the conversation was centered around user requests.
• Pre-Summary State: The agent was discussing the implementation of the requested changes when the token budget was exceeded.
• Operation Context: The commands were e...

Created from VS Code via the GitHub Pull Request extension.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ SoonIter
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[SoonIter]

@copilot

headers 为空时，仍然要显示，不过 UI 会有所变化

UI 如图所示，请单独描述 headers 为空时的 UI

[netlify]

✅ Deploy Preview for rspress-v2 ready!

Name	Link
🔨 Latest commit	02fd932
🔍 Latest deploy log	https://app.netlify.com/projects/rspress-v2/deploys/69424da1bb14b600088f07e6
😎 Deploy Preview	https://deploy-preview-2899--rspress-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

@copilot

headers 为空时，仍然要显示，不过 UI 会有所变化
...

Updated in commit 02fd932. Items without headers now display in a responsive grid layout (4 columns desktop, 3 tablet, 2 mobile, 1 small mobile) similar to the screenshot you provided.

UI for items without headers:

• Simple bordered cards in a responsive grid
• No split layout (no left/right sections)
• Clean card design with just the title/link
• Responsive: 4→3→2→1 columns based on screen width

UI for items with headers (unchanged):

• Standard split layout with title on left, headers on right

Screenshot: https://github.com/user-attachments/assets/10b1b824-3911-4eb5-b17d-1ce5c4b717c2

[netlify]

✅ Deploy Preview for rspress-v2 ready!

Name	Link
🔨 Latest commit	2a0524f
🔍 Latest deploy log	https://app.netlify.com/projects/rspress-v2/deploys/6942baef8549c400085b3d56
😎 Deploy Preview	https://deploy-preview-2899--rspress-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[SoonIter]

@copilot 自动 rebase 到 main

[Copilot]

@copilot 自动 rebase 到 main

I don't have the capability to perform git rebase operations. You'll need to manually rebase this branch onto main using:

git fetch origin
git rebase origin/main
git push --force-with-lease

Or use GitHub's UI to update the branch if there are conflicts that need resolution.

[github-actions]

Rsdoctor Bundle Diff Analysis

📊 Quick Summary (Click to expand)

Project	Total Size	Change
web	14.9 MB	➡️ 5.0 KB (0.0%)

📁 web

Path: website/doc_build/web/rsdoctor-data.json

📌 Baseline Commit: e86fde2df5 | PR: #2319

Metric	Current	Baseline	Change
📊 Total Size	14.9 MB	14.9 MB	5.0 KB (0.0%)
📄 JavaScript	14.3 MB	14.3 MB	3.4 KB (0.0%)
🎨 CSS	115.4 KB	114.2 KB	+1.2 KB (+1.0%)
🌐 HTML	0 B	0 B	N/A
📁 Other Assets	512.9 KB	512.5 KB	431.0 B (0.1%)

📦 Download Diff Report: web Bundle Diff

Generated by Rsdoctor GitHub Action

[SoonIter]

@copilot 修复 CI 测试

[Copilot]

@copilot 修复 CI 测试

Fixed in commit e5a8449. The lint error was caused by incorrect heading case in test fixture files. Changed headings to lowercase to match the heading-case linter requirements:

• "Feature A/B" → "feature a/b"
• "Section 1/2" → "section a/b"

The lint now passes successfully.

[Copilot]

Pull request overview

This PR improves the visual presentation of Overview pages in the Rspress documentation system by implementing a responsive grid layout for items that don't contain subheadings (h2/h3 headers), while maintaining the existing split layout for items with content sections.

Key changes:

• Separated overview items into two groups based on content presence and rendered them with different layouts
• Added responsive grid styling (4/3/2/1 columns) for simple overview items
• Updated E2E tests to handle both layout patterns

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/core/src/theme/components/OverviewGroup/index.tsx	Added logic to separate items by content presence and render them in different layouts (split or grid)
packages/core/src/theme/components/OverviewGroup/index.scss	Added CSS variables, grid layout styles, and responsive breakpoints for the new grid display
website/docs/en/ui/runtime-components/index.mdx	Created overview index page with frontmatter configuration
website/docs/en/ui/runtime-components/head.mdx	Added overviewHeaders: [] frontmatter to indicate no headers for grid display
website/docs/en/ui/runtime-components/no-ssr.mdx	Added overviewHeaders: [] frontmatter to indicate no headers for grid display
website/docs/zh/ui/runtime-components/index.mdx	Created Chinese overview index page with frontmatter configuration
website/docs/zh/ui/runtime-components/head.mdx	Added overviewHeaders: [] frontmatter to indicate no headers for grid display
website/docs/zh/ui/runtime-components/no-ssr.mdx	Added overviewHeaders: [] frontmatter to indicate no headers for grid display
e2e/fixtures/nested-overview/index.test.ts	Updated tests to query both standard and grid layout items and verify combined results
e2e/fixtures/nested-overview/doc/basic-level-1/level-2/two.mdx	Added test content with section headers for verification
e2e/fixtures/nested-overview/doc/basic-level-1/level-2/level-3/three.mdx	Added test content with feature headers for verification
e2e/fixtures/auto-nav-sidebar/index.test.ts	Updated test expectations to reflect reordered overview items

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.