From 2c33bedac296958a403c65e41ffec9b8f0756278 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 22:32:17 +0700
Subject: [PATCH 01/13] feat: add group-name parameter support for code groups

- Add optional group-name parameter to code-group containers
- Validates group names (alphanumeric, hyphens, underscores only)
- Adds data-group-name attribute to generated HTML
- Includes E2E tests for validation and functionality
- Updates documentation with usage examples and guidelines
---
 DOC-GROUP-CHANGES.md                          | 434 ++++++++++++++++++
 __tests__/e2e/markdown-extensions/index.md    |  56 +++
 .../markdown-extensions.test.ts               |  43 ++
 docs/en/guide/markdown.md                     |  54 +++
 src/node/markdown/plugins/containers.ts       |  19 +-
 5 files changed, 605 insertions(+), 1 deletion(-)
 create mode 100644 DOC-GROUP-CHANGES.md

diff --git a/DOC-GROUP-CHANGES.md b/DOC-GROUP-CHANGES.md
new file mode 100644
index 000000000000..bbf05e453c7f
--- /dev/null
+++ b/DOC-GROUP-CHANGES.md
@@ -0,0 +1,434 @@
+# Code Group Name Feature - Implementation Plan
+
+## Overview
+
+Add support for named code groups via the `group-name` parameter in the code-group container syntax. This allows developers to semantically identify and potentially sync code groups across a documentation site.
+
+## Feature Specification
+
+### Markdown Syntax
+
+**Current:**
+```markdown
+::: code-group
+
+```js [config.js]
+// code
+```
+
+:::
+```
+
+**New:**
+```markdown
+::: code-group group-name=installs
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+:::
+```
+
+**Note:** Group names must not contain whitespace. Use hyphens, underscores, or camelCase instead.
+
+### HTML Output
+
+**Current:**
+```html
+<div class="vp-code-group">
+  <div class="tabs">...</div>
+  <div class="blocks">...</div>
+</div>
+```
+
+**New:**
+```html
+<div class="vp-code-group" data-group-name="installs">
+  <div class="tabs">...</div>
+  <div class="blocks">...</div>
+</div>
+```
+
+## Implementation Plan
+
+### 1. Core Changes
+
+#### File: `/src/node/markdown/plugins/containers.ts`
+
+**Function:** `createCodeGroup()`
+
+**Changes Required:**
+- Parse the `token.info` string to extract `group-name=value` parameter
+- Extract and validate the group name value
+- Add `data-group-name` attribute to the opening `<div class="vp-code-group">` tag
+- Handle edge cases:
+  - Empty group name: `group-name=` → ignore
+  - Whitespace in name: reject/ignore (group names must not contain whitespace)
+  - Special characters: allow only alphanumeric, hyphens, underscores
+  - Invalid syntax: gracefully ignore and render without attribute
+
+**Implementation approach:**
+```typescript
+// Pseudo-code
+function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
+  return [
+    container,
+    'code-group',
+    {
+      render(tokens, idx) {
+        if (tokens[idx].nesting === 1) {
+          const token = tokens[idx]
+          const info = token.info.trim()
+          
+          // Extract group-name parameter
+          const groupNameMatch = info.match(/group-name=(\S+)/)
+          let groupName = groupNameMatch ? groupNameMatch[1] : null
+          
+          // Validate: only allow alphanumeric, hyphens, and underscores
+          if (groupName && !/^[a-zA-Z0-9_-]+$/.test(groupName)) {
+            groupName = null // Invalid group name, ignore
+          }
+          
+          // Build data attribute
+          const groupNameAttr = groupName ? 
+            ` data-group-name="${md.utils.escapeHtml(groupName)}"` : ''
+          
+          // ... existing tab generation logic ...
+          
+          return `<div class="vp-code-group"${groupNameAttr}><div class="tabs">${tabs}</div><div class="blocks">\n`
+        }
+        return `</div></div>\n`
+      }
+    }
+  ]
+}
+```
+
+### 2. Type Definitions
+
+#### File: `/src/shared/shared.ts` or appropriate type definition file
+
+**Changes Required:**
+- No TypeScript interface changes needed (HTML data attributes are dynamic)
+- Document the new attribute in JSDoc comments if applicable
+
+### 3. Client-Side Changes (Optional for Future Enhancement)
+
+#### File: `/src/client/app/composables/codeGroups.ts`
+
+**Current scope:** No immediate changes required for basic implementation
+
+**Future enhancement possibilities:**
+- Sync tab selection across code groups with the same `group-name`
+- Store selection preference in localStorage per group name
+- Emit events for cross-component synchronization
+
+### 4. Styling Changes
+
+#### File: `/src/client/theme-default/styles/components/vp-code-group.css`
+
+**Changes Required:**
+- No CSS changes needed for basic implementation
+- The `data-group-name` attribute is purely semantic for this iteration
+- Could add attribute selectors for future styling: `[data-group-name="installs"]`
+
+## Testing Strategy
+
+### 1. Unit Tests
+
+**File:** `/__tests__/unit/node/markdown-container.test.ts` (create if doesn't exist)
+
+**Test cases:**
+- ✅ Parse basic group-name parameter: `group-name=installs`
+- ✅ Parse group-name with hyphens: `group-name=install-methods`
+- ✅ Parse group-name with underscores: `group-name=install_methods`
+- ✅ Parse group-name with camelCase: `group-name=installMethods`
+- ✅ Handle missing group-name (no parameter)
+- ✅ Handle empty group-name: `group-name=`
+- ✅ Reject group-name with spaces: `group-name="install methods"` → ignore
+- ✅ Reject group-name with invalid characters: `group-name=install@methods` → ignore
+- ✅ Verify data attribute is properly added to HTML output
+- ✅ Verify existing functionality not broken
+
+### 2. E2E Tests
+
+**File:** `/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts`
+
+**New test suite:**
+```typescript
+describe('Code Groups with Names', () => {
+  test('basic group-name attribute', async () => {
+    const div = page.locator('#group-name-basic + div')
+    
+    // Verify data attribute exists
+    const groupName = await div.getAttribute('data-group-name')
+    expect(groupName).toBe('installs')
+    
+    // Verify tabs still work
+    const labels = div.locator('.tabs > label')
+    expect(await labels.count()).toBe(2)
+    
+    // Verify clicking still switches tabs
+    await labels.nth(1).click()
+    const blocks = div.locator('.blocks > div')
+    expect(await getClassList(blocks.nth(1))).toContain('active')
+  })
+  
+  test('group-name with quotes', async () => {
+    const div = page.locator('#group-name-quoted + div')
+    const groupName = await div.getAttribute('data-group-name')
+    // Quoted names with spaces should be rejected
+    expect(groupName).toBeNull()
+  })
+  
+  test('code-group without group-name', async () => {
+    const div = page.locator('#basic-code-group + div')
+    const groupName = await div.getAttribute('data-group-name')
+    expect(groupName).toBeNull()
+  })
+  
+  test('group-name with hyphens and underscores', async () => {
+    const div = page.locator('#group-name-special + div')
+    const groupName = await div.getAttribute('data-group-name')
+    expect(groupName).toBe('install_methods-v2')
+  })
+  
+  test('group-name with invalid characters', async () => {
+    const div = page.locator('#group-name-invalid + div')
+    const groupName = await div.getAttribute('data-group-name')
+    // Should be rejected due to invalid characters
+    expect(groupName).toBeNull()
+  })
+})
+```
+
+**Test fixtures:** `/__tests__/e2e/markdown-extensions/index.md`
+
+Add new markdown sections:
+```markdown
+### Group Name Basic
+
+::: code-group group-name=installs
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+:::
+
+### Group Name Quoted (Should be Rejected)
+
+::: code-group group-name="install methods"
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+### Group Name with Hyphens and Underscores
+
+::: code-group group-name=install_methods-v2
+
+```bash [npm]
+npm install vitepress@next
+```
+
+```bash [pnpm]
+pnpm add vitepress@next
+```
+
+:::
+
+### Group Name Invalid Characters (Should be Rejected)
+
+::: code-group group-name=install@methods!
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+:::
+```
+
+### 3. Manual Testing Checklist
+
+- [ ] Code group renders correctly in dev mode
+- [ ] Code group renders correctly in build mode
+- [ ] Tab switching works with group-name attribute
+- [ ] Multiple code groups on same page work independently
+- [ ] Code groups with same group-name attribute render correctly
+- [ ] Group name with hyphens works
+- [ ] Group name with underscores works
+- [ ] Group name with spaces is rejected (no attribute added)
+- [ ] Group name with invalid characters is rejected
+- [ ] Code group without group-name still works (backward compatibility)
+- [ ] Imported snippets work with group-name
+- [ ] Hot module reload works in dev mode
+
+## Documentation Updates
+
+### 1. Main Documentation
+
+**File:** `/docs/en/guide/markdown.md`
+
+**Section:** Code Groups (around line 690)
+
+**Addition:**
+
+```markdown
+### Named Code Groups
+
+You can optionally name code groups using the `group-name` parameter. This can be useful for semantic identification and potential future features like syncing tab selections across groups.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+````
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+Named code groups add a `data-group-name` attribute to the generated HTML, which can be useful for custom styling or scripting.
+:::
+```
+
+### 2. API/Reference Documentation
+
+**File:** `/docs/en/reference/default-theme-config.md` or appropriate reference doc
+
+**If applicable:** Document the HTML structure and data attributes
+
+### 3. Internationalization
+
+Update the following language versions with translated content:
+- `/docs/es/guide/markdown.md`
+- `/docs/ja/guide/markdown.md`
+- `/docs/ko/guide/markdown.md`
+- `/docs/pt/guide/markdown.md`
+- `/docs/ru/guide/markdown.md`
+- `/docs/zh/guide/markdown.md`
+- `/docs/fa/guide/markdown.md`
+
+**Note:** Initial PR can focus on English docs, with i18n as follow-up PRs.
+
+## Migration & Backward Compatibility
+
+### Breaking Changes
+**None.** This is a purely additive feature.
+
+### Backward Compatibility
+- All existing code groups without `group-name` parameter continue to work exactly as before
+- The parameter is optional and doesn't change default behavior
+- No configuration changes required
+
+## Future Enhancements (Out of Scope for Initial PR)
+
+1. **Tab Synchronization**
+   - Sync tab selection across all code groups with the same `group-name`
+   - Example: Selecting "npm" in one "package-managers" group auto-selects "npm" in all other "package-managers" groups
+
+2. **LocalStorage Persistence**
+   - Remember user's last selected tab per group-name
+   - Restore selection on page load/navigation
+
+3. **Custom Styling Hooks**
+   - CSS variables for group-specific styling
+   - Example: Different color schemes per group-name
+
+4. **Programmatic API**
+   - JavaScript API to control code group tab selection
+   - Events for tab changes
+
+## Implementation Timeline
+
+1. **Phase 1:** Core implementation (containers.ts)
+2. **Phase 2:** Testing (unit + e2e)
+3. **Phase 3:** Documentation (English)
+4. **Phase 4:** Code review and refinement
+5. **Phase 5:** i18n documentation (can be separate PRs)
+
+## Files to Modify
+
+### Required Changes
+- ✅ `/src/node/markdown/plugins/containers.ts` - Core logic
+- ✅ `/__tests__/e2e/markdown-extensions/index.md` - Test fixtures
+- ✅ `/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts` - E2E tests
+- ✅ `/docs/en/guide/markdown.md` - Documentation
+
+### Optional/Future
+- ⏭️ `/src/client/app/composables/codeGroups.ts` - Tab sync feature
+- ⏭️ All i18n documentation files
+
+## Success Criteria
+
+- [ ] Group-name parameter is correctly parsed from markdown
+- [ ] HTML output includes `data-group-name` attribute when specified
+- [ ] All tests pass (existing + new)
+- [ ] Documentation is clear and includes examples
+- [ ] No regression in existing code group functionality
+- [ ] Code follows VitePress contribution guidelines
+- [ ] Commit messages follow convention
+
+## Notes
+
+- Keep the implementation simple and focused for the initial version
+- Ensure proper HTML escaping to prevent XSS vulnerabilities
+- Consider edge cases in parsing (quotes, special chars, etc.)
+- Maintain consistency with existing VitePress container syntax patterns
diff --git a/__tests__/e2e/markdown-extensions/index.md b/__tests__/e2e/markdown-extensions/index.md
index 3446b4efdb1e..7d19b49d56c4 100644
--- a/__tests__/e2e/markdown-extensions/index.md
+++ b/__tests__/e2e/markdown-extensions/index.md
@@ -173,6 +173,62 @@ export default config
 
 :::
 
+### Group Name Basic
+
+::: code-group group-name=installs
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+:::
+
+### Group Name with Hyphens and Underscores
+
+::: code-group group-name=install_methods-v2
+
+```bash [npm]
+npm install vitepress@next
+```
+
+```bash [pnpm]
+pnpm add vitepress@next
+```
+
+:::
+
+### Group Name with Spaces (Should be Rejected)
+
+::: code-group group-name="install methods"
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+### Group Name with Invalid Characters (Should be Rejected)
+
+::: code-group group-name=install@methods!
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+:::
+
 ## Markdown File Inclusion
 
 <!--@include: ./foo.md-->
diff --git a/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts b/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
index 839f953cba9e..3cbc54351794 100644
--- a/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
+++ b/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
@@ -91,6 +91,10 @@ describe('Table of Contents', () => {
         "Code Groups",
         "Basic Code Group",
         "With Other Features",
+        "Group Name Basic",
+        "Group Name with Hyphens and Underscores",
+        "Group Name with Spaces (Should be Rejected)",
+        "Group Name with Invalid Characters (Should be Rejected)",
         "Markdown File Inclusion",
         "Region",
         "Markdown At File Inclusion",
@@ -277,6 +281,45 @@ describe('Code Groups', () => {
       await getClassList(blocks.nth(1).locator('code > span').nth(0))
     ).toContain('highlighted')
   })
+
+  test('group-name basic', async () => {
+    const div = page.locator('#group-name-basic + div')
+
+    // Verify data attribute exists
+    const groupName = await div.getAttribute('data-group-name')
+    expect(groupName).toBe('installs')
+
+    // Verify tabs still work
+    const labels = div.locator('.tabs > label')
+    expect(await labels.count()).toBe(2)
+
+    // Verify clicking still switches tabs
+    await labels.nth(1).click()
+    const blocks = div.locator('.blocks > div')
+    expect(await getClassList(blocks.nth(1))).toContain('active')
+  })
+
+  test('group-name with hyphens and underscores', async () => {
+    const div = page.locator('#group-name-with-hyphens-and-underscores + div')
+    const groupName = await div.getAttribute('data-group-name')
+    expect(groupName).toBe('install_methods-v2')
+  })
+
+  test('group-name with spaces should be rejected', async () => {
+    const div = page.locator('#group-name-with-spaces-should-be-rejected + div')
+    const groupName = await div.getAttribute('data-group-name')
+    // Quoted names with spaces should be rejected
+    expect(groupName).toBeNull()
+  })
+
+  test('group-name with invalid characters should be rejected', async () => {
+    const div = page.locator(
+      '#group-name-with-invalid-characters-should-be-rejected + div'
+    )
+    const groupName = await div.getAttribute('data-group-name')
+    // Should be rejected due to invalid characters
+    expect(groupName).toBeNull()
+  })
 })
 
 describe('Markdown File Inclusion', () => {
diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index e1be3e6b366f..16c0b5389f9f 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -776,6 +776,60 @@ You can also [import snippets](#import-code-snippets) in code groups:
 
 :::
 
+### Named Code Groups
+
+You can optionally name code groups using the `group-name` parameter. This can be useful for semantic identification and potential future features like syncing tab selections across groups.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+````
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+Named code groups add a `data-group-name` attribute to the generated HTML, which can be useful for custom styling or scripting.
+:::
+
 ## Markdown File Inclusion
 
 You can include a markdown file in another markdown file, even nested.
diff --git a/src/node/markdown/plugins/containers.ts b/src/node/markdown/plugins/containers.ts
index 39efce17fd2f..d4e3b8152ebc 100644
--- a/src/node/markdown/plugins/containers.ts
+++ b/src/node/markdown/plugins/containers.ts
@@ -64,6 +64,23 @@ function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
     {
       render(tokens, idx) {
         if (tokens[idx].nesting === 1) {
+          const token = tokens[idx]
+          const info = token.info.trim()
+
+          // Extract group-name parameter
+          const groupNameMatch = info.match(/group-name=(\S+)/)
+          let groupName = groupNameMatch ? groupNameMatch[1] : null
+
+          // Validate: only allow alphanumeric, hyphens, and underscores
+          if (groupName && !/^[a-zA-Z0-9_-]+$/.test(groupName)) {
+            groupName = null
+          }
+
+          // Build data attribute
+          const groupNameAttr = groupName
+            ? ` data-group-name="${md.utils.escapeHtml(groupName)}"`
+            : ''
+
           let tabs = ''
           let checked = 'checked'
 
@@ -95,7 +112,7 @@ function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
             }
           }
 
-          return `<div class="vp-code-group"><div class="tabs">${tabs}</div><div class="blocks">\n`
+          return `<div class="vp-code-group"${groupNameAttr}><div class="tabs">${tabs}</div><div class="blocks">\n`
         }
         return `</div></div>\n`
       }

From 6e26da905e74d44be10b0ad8a2a8d905d62c6c96 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 22:36:46 +0700
Subject: [PATCH 02/13] feat: implement tab synchronization for named code
 groups

- Add syncTabsInOtherGroups function to sync tabs across groups
- When clicking a tab in a named group, all groups with same name sync
- Add E2E test for synchronization behavior
- Update documentation to explain sync purpose and usage
- Add second test fixture for testing sync between groups
---
 DOC-GROUP-CHANGES.md                          | 51 ++++++++++++++++---
 __tests__/e2e/markdown-extensions/index.md    | 14 +++++
 .../markdown-extensions.test.ts               | 42 +++++++++++++++
 docs/en/guide/markdown.md                     | 24 ++++++++-
 src/client/app/composables/codeGroups.ts      | 38 ++++++++++++++
 5 files changed, 160 insertions(+), 9 deletions(-)

diff --git a/DOC-GROUP-CHANGES.md b/DOC-GROUP-CHANGES.md
index bbf05e453c7f..b15a47a7dd57 100644
--- a/DOC-GROUP-CHANGES.md
+++ b/DOC-GROUP-CHANGES.md
@@ -2,10 +2,14 @@
 
 ## Overview
 
-Add support for named code groups via the `group-name` parameter in the code-group container syntax. This allows developers to semantically identify and potentially sync code groups across a documentation site.
+Add support for named code groups via the `group-name` parameter in the code-group container syntax. This allows **synchronization of tab selections across multiple code groups** with the same name on a page.
 
 ## Feature Specification
 
+### Purpose
+
+When multiple code groups share the same `group-name`, selecting a tab in one group automatically selects the corresponding tab in all other groups with the same name. This is useful for documentation that shows the same tool (e.g., package managers) in multiple contexts.
+
 ### Markdown Syntax
 
 **Current:**
@@ -117,16 +121,49 @@ function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
 - No TypeScript interface changes needed (HTML data attributes are dynamic)
 - Document the new attribute in JSDoc comments if applicable
 
-### 3. Client-Side Changes (Optional for Future Enhancement)
+### 3. Client-Side Changes
 
 #### File: `/src/client/app/composables/codeGroups.ts`
 
-**Current scope:** No immediate changes required for basic implementation
+**Changes Required:**
+- Add tab synchronization logic when a tab is clicked
+- Find all code groups with the same `data-group-name` attribute
+- Update their selected tabs to match the clicked tab
+- Ensure proper DOM updates for both radio inputs and active blocks
 
-**Future enhancement possibilities:**
-- Sync tab selection across code groups with the same `group-name`
-- Store selection preference in localStorage per group name
-- Emit events for cross-component synchronization
+**Implementation:**
+```typescript
+function syncTabsInOtherGroups(
+  groupName: string,
+  tabIndex: number,
+  currentGroup: HTMLElement
+) {
+  // Find all code groups with the same group-name
+  const groups = document.querySelectorAll(
+    `.vp-code-group[data-group-name="${groupName}"]`
+  )
+
+  groups.forEach((g) => {
+    // Skip the current group that was clicked
+    if (g === currentGroup) return
+
+    const inputs = g.querySelectorAll('input')
+    const blocks = g.querySelector('.blocks')
+    if (!blocks || !inputs[tabIndex]) return
+
+    // Update radio input
+    inputs[tabIndex].checked = true
+
+    // Update active block
+    const currentActive = blocks.querySelector('.active')
+    const newActive = blocks.children[tabIndex]
+    if (currentActive && newActive && currentActive !== newActive) {
+      currentActive.classList.remove('active')
+      newActive.classList.add('active')
+    }
+  })
+}
+```
 
 ### 4. Styling Changes
 
diff --git a/__tests__/e2e/markdown-extensions/index.md b/__tests__/e2e/markdown-extensions/index.md
index 7d19b49d56c4..af2843bd249d 100644
--- a/__tests__/e2e/markdown-extensions/index.md
+++ b/__tests__/e2e/markdown-extensions/index.md
@@ -187,6 +187,20 @@ pnpm add vitepress
 
 :::
 
+### Group Name Second Instance (Same Name for Sync Test)
+
+::: code-group group-name=installs
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+:::
+
 ### Group Name with Hyphens and Underscores
 
 ::: code-group group-name=install_methods-v2
diff --git a/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts b/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
index 3cbc54351794..312eef77da7f 100644
--- a/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
+++ b/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
@@ -92,6 +92,7 @@ describe('Table of Contents', () => {
         "Basic Code Group",
         "With Other Features",
         "Group Name Basic",
+        "Group Name Second Instance (Same Name for Sync Test)",
         "Group Name with Hyphens and Underscores",
         "Group Name with Spaces (Should be Rejected)",
         "Group Name with Invalid Characters (Should be Rejected)",
@@ -299,6 +300,47 @@ describe('Code Groups', () => {
     expect(await getClassList(blocks.nth(1))).toContain('active')
   })
 
+  test('group-name synchronization across groups', async () => {
+    const div1 = page.locator('#group-name-basic + div')
+    const div2 = page.locator(
+      '#group-name-second-instance-same-name-for-sync-test + div'
+    )
+
+    // Both groups should have the same group-name
+    expect(await div1.getAttribute('data-group-name')).toBe('installs')
+    expect(await div2.getAttribute('data-group-name')).toBe('installs')
+
+    // Initially, both should have first tab active
+    expect(await getClassList(div1.locator('.blocks > div').nth(0))).toContain(
+      'active'
+    )
+    expect(await getClassList(div2.locator('.blocks > div').nth(0))).toContain(
+      'active'
+    )
+
+    // Click second tab in first group
+    await div1.locator('.tabs > label').nth(1).click()
+
+    // Both groups should now have second tab active (synced)
+    expect(await getClassList(div1.locator('.blocks > div').nth(1))).toContain(
+      'active'
+    )
+    expect(await getClassList(div2.locator('.blocks > div').nth(1))).toContain(
+      'active'
+    )
+
+    // Click first tab in second group
+    await div2.locator('.tabs > label').nth(0).click()
+
+    // Both groups should now have first tab active again (synced back)
+    expect(await getClassList(div1.locator('.blocks > div').nth(0))).toContain(
+      'active'
+    )
+    expect(await getClassList(div2.locator('.blocks > div').nth(0))).toContain(
+      'active'
+    )
+  })
+
   test('group-name with hyphens and underscores', async () => {
     const div = page.locator('#group-name-with-hyphens-and-underscores + div')
     const groupName = await div.getAttribute('data-group-name')
diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index 16c0b5389f9f..ffbedf194596 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -778,7 +778,7 @@ You can also [import snippets](#import-code-snippets) in code groups:
 
 ### Named Code Groups
 
-You can optionally name code groups using the `group-name` parameter. This can be useful for semantic identification and potential future features like syncing tab selections across groups.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
@@ -797,9 +797,29 @@ pnpm add vitepress
 yarn add vitepress
 ```
 
+:::
+
+Later in the same page:
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
 :::
 ````
 
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
 **Output**
 
 ::: code-group group-name=package-managers
@@ -827,7 +847,7 @@ Valid examples:
 - `group-name=installMethods`
 
 ::: tip
-Named code groups add a `data-group-name` attribute to the generated HTML, which can be useful for custom styling or scripting.
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
 :::
 
 ## Markdown File Inclusion
diff --git a/src/client/app/composables/codeGroups.ts b/src/client/app/composables/codeGroups.ts
index d8a38ba72741..e01a25845d71 100644
--- a/src/client/app/composables/codeGroups.ts
+++ b/src/client/app/composables/codeGroups.ts
@@ -24,6 +24,7 @@ export function useCodeGroups() {
         const i = Array.from(group.querySelectorAll('input')).indexOf(el)
         if (i < 0) return
 
+        // Update current group
         const blocks = group.querySelector('.blocks')
         if (!blocks) return
 
@@ -40,7 +41,44 @@ export function useCodeGroups() {
 
         const label = group?.querySelector(`label[for="${el.id}"]`)
         label?.scrollIntoView({ block: 'nearest' })
+
+        // Sync other groups with same group-name
+        const groupName = group.getAttribute('data-group-name')
+        if (groupName) {
+          syncTabsInOtherGroups(groupName, i, group as HTMLElement)
+        }
       }
     })
   }
 }
+
+function syncTabsInOtherGroups(
+  groupName: string,
+  tabIndex: number,
+  currentGroup: HTMLElement
+) {
+  // Find all code groups with the same group-name
+  const groups = document.querySelectorAll(
+    `.vp-code-group[data-group-name="${groupName}"]`
+  )
+
+  groups.forEach((g) => {
+    // Skip the current group that was clicked
+    if (g === currentGroup) return
+
+    const inputs = g.querySelectorAll('input')
+    const blocks = g.querySelector('.blocks')
+    if (!blocks || !inputs[tabIndex]) return
+
+    // Update radio input
+    inputs[tabIndex].checked = true
+
+    // Update active block
+    const currentActive = blocks.querySelector('.active')
+    const newActive = blocks.children[tabIndex]
+    if (currentActive && newActive && currentActive !== newActive) {
+      currentActive.classList.remove('active')
+      newActive.classList.add('active')
+    }
+  })
+}

From d8362cc0fec3d01065190257bdd1f637755186e6 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 22:38:10 +0700
Subject: [PATCH 03/13] docs: show both code groups in sync example

- Add second code group to output section
- Users can now actually test the synchronization behavior
- Add tip to encourage trying the interactive demo
---
 docs/en/guide/markdown.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index ffbedf194596..cb982fa894cd 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -838,6 +838,26 @@ yarn add vitepress
 
 :::
 
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:

From 16cdd4299cc23efaeee623478fbcca53e3d3a443 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 22:41:15 +0700
Subject: [PATCH 04/13] docs: convert text to comment in code group example

---
 docs/en/guide/markdown.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index cb982fa894cd..99ea3dbd28d0 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -799,7 +799,7 @@ yarn add vitepress
 
 :::
 
-Later in the same page:
+<!-- Later in the same page: -->
 
 ::: code-group group-name=package-managers
 

From 1b98671b04426e11a8fb27ce4e4c53ca9e72098f Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 22:50:59 +0700
Subject: [PATCH 05/13] docs: remove implementation plan document

---
 DOC-GROUP-CHANGES.md | 471 -------------------------------------------
 1 file changed, 471 deletions(-)
 delete mode 100644 DOC-GROUP-CHANGES.md

diff --git a/DOC-GROUP-CHANGES.md b/DOC-GROUP-CHANGES.md
deleted file mode 100644
index b15a47a7dd57..000000000000
--- a/DOC-GROUP-CHANGES.md
+++ /dev/null
@@ -1,471 +0,0 @@
-# Code Group Name Feature - Implementation Plan
-
-## Overview
-
-Add support for named code groups via the `group-name` parameter in the code-group container syntax. This allows **synchronization of tab selections across multiple code groups** with the same name on a page.
-
-## Feature Specification
-
-### Purpose
-
-When multiple code groups share the same `group-name`, selecting a tab in one group automatically selects the corresponding tab in all other groups with the same name. This is useful for documentation that shows the same tool (e.g., package managers) in multiple contexts.
-
-### Markdown Syntax
-
-**Current:**
-```markdown
-::: code-group
-
-```js [config.js]
-// code
-```
-
-:::
-```
-
-**New:**
-```markdown
-::: code-group group-name=installs
-
-```bash [npm]
-npm install vitepress
-```
-
-```bash [pnpm]
-pnpm add vitepress
-```
-
-:::
-```
-
-**Note:** Group names must not contain whitespace. Use hyphens, underscores, or camelCase instead.
-
-### HTML Output
-
-**Current:**
-```html
-<div class="vp-code-group">
-  <div class="tabs">...</div>
-  <div class="blocks">...</div>
-</div>
-```
-
-**New:**
-```html
-<div class="vp-code-group" data-group-name="installs">
-  <div class="tabs">...</div>
-  <div class="blocks">...</div>
-</div>
-```
-
-## Implementation Plan
-
-### 1. Core Changes
-
-#### File: `/src/node/markdown/plugins/containers.ts`
-
-**Function:** `createCodeGroup()`
-
-**Changes Required:**
-- Parse the `token.info` string to extract `group-name=value` parameter
-- Extract and validate the group name value
-- Add `data-group-name` attribute to the opening `<div class="vp-code-group">` tag
-- Handle edge cases:
-  - Empty group name: `group-name=` → ignore
-  - Whitespace in name: reject/ignore (group names must not contain whitespace)
-  - Special characters: allow only alphanumeric, hyphens, underscores
-  - Invalid syntax: gracefully ignore and render without attribute
-
-**Implementation approach:**
-```typescript
-// Pseudo-code
-function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
-  return [
-    container,
-    'code-group',
-    {
-      render(tokens, idx) {
-        if (tokens[idx].nesting === 1) {
-          const token = tokens[idx]
-          const info = token.info.trim()
-          
-          // Extract group-name parameter
-          const groupNameMatch = info.match(/group-name=(\S+)/)
-          let groupName = groupNameMatch ? groupNameMatch[1] : null
-          
-          // Validate: only allow alphanumeric, hyphens, and underscores
-          if (groupName && !/^[a-zA-Z0-9_-]+$/.test(groupName)) {
-            groupName = null // Invalid group name, ignore
-          }
-          
-          // Build data attribute
-          const groupNameAttr = groupName ? 
-            ` data-group-name="${md.utils.escapeHtml(groupName)}"` : ''
-          
-          // ... existing tab generation logic ...
-          
-          return `<div class="vp-code-group"${groupNameAttr}><div class="tabs">${tabs}</div><div class="blocks">\n`
-        }
-        return `</div></div>\n`
-      }
-    }
-  ]
-}
-```
-
-### 2. Type Definitions
-
-#### File: `/src/shared/shared.ts` or appropriate type definition file
-
-**Changes Required:**
-- No TypeScript interface changes needed (HTML data attributes are dynamic)
-- Document the new attribute in JSDoc comments if applicable
-
-### 3. Client-Side Changes
-
-#### File: `/src/client/app/composables/codeGroups.ts`
-
-**Changes Required:**
-- Add tab synchronization logic when a tab is clicked
-- Find all code groups with the same `data-group-name` attribute
-- Update their selected tabs to match the clicked tab
-- Ensure proper DOM updates for both radio inputs and active blocks
-
-**Implementation:**
-```typescript
-function syncTabsInOtherGroups(
-  groupName: string,
-  tabIndex: number,
-  currentGroup: HTMLElement
-) {
-  // Find all code groups with the same group-name
-  const groups = document.querySelectorAll(
-    `.vp-code-group[data-group-name="${groupName}"]`
-  )
-
-  groups.forEach((g) => {
-    // Skip the current group that was clicked
-    if (g === currentGroup) return
-
-    const inputs = g.querySelectorAll('input')
-    const blocks = g.querySelector('.blocks')
-    if (!blocks || !inputs[tabIndex]) return
-
-    // Update radio input
-    inputs[tabIndex].checked = true
-
-    // Update active block
-    const currentActive = blocks.querySelector('.active')
-    const newActive = blocks.children[tabIndex]
-    if (currentActive && newActive && currentActive !== newActive) {
-      currentActive.classList.remove('active')
-      newActive.classList.add('active')
-    }
-  })
-}
-```
-
-### 4. Styling Changes
-
-#### File: `/src/client/theme-default/styles/components/vp-code-group.css`
-
-**Changes Required:**
-- No CSS changes needed for basic implementation
-- The `data-group-name` attribute is purely semantic for this iteration
-- Could add attribute selectors for future styling: `[data-group-name="installs"]`
-
-## Testing Strategy
-
-### 1. Unit Tests
-
-**File:** `/__tests__/unit/node/markdown-container.test.ts` (create if doesn't exist)
-
-**Test cases:**
-- ✅ Parse basic group-name parameter: `group-name=installs`
-- ✅ Parse group-name with hyphens: `group-name=install-methods`
-- ✅ Parse group-name with underscores: `group-name=install_methods`
-- ✅ Parse group-name with camelCase: `group-name=installMethods`
-- ✅ Handle missing group-name (no parameter)
-- ✅ Handle empty group-name: `group-name=`
-- ✅ Reject group-name with spaces: `group-name="install methods"` → ignore
-- ✅ Reject group-name with invalid characters: `group-name=install@methods` → ignore
-- ✅ Verify data attribute is properly added to HTML output
-- ✅ Verify existing functionality not broken
-
-### 2. E2E Tests
-
-**File:** `/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts`
-
-**New test suite:**
-```typescript
-describe('Code Groups with Names', () => {
-  test('basic group-name attribute', async () => {
-    const div = page.locator('#group-name-basic + div')
-    
-    // Verify data attribute exists
-    const groupName = await div.getAttribute('data-group-name')
-    expect(groupName).toBe('installs')
-    
-    // Verify tabs still work
-    const labels = div.locator('.tabs > label')
-    expect(await labels.count()).toBe(2)
-    
-    // Verify clicking still switches tabs
-    await labels.nth(1).click()
-    const blocks = div.locator('.blocks > div')
-    expect(await getClassList(blocks.nth(1))).toContain('active')
-  })
-  
-  test('group-name with quotes', async () => {
-    const div = page.locator('#group-name-quoted + div')
-    const groupName = await div.getAttribute('data-group-name')
-    // Quoted names with spaces should be rejected
-    expect(groupName).toBeNull()
-  })
-  
-  test('code-group without group-name', async () => {
-    const div = page.locator('#basic-code-group + div')
-    const groupName = await div.getAttribute('data-group-name')
-    expect(groupName).toBeNull()
-  })
-  
-  test('group-name with hyphens and underscores', async () => {
-    const div = page.locator('#group-name-special + div')
-    const groupName = await div.getAttribute('data-group-name')
-    expect(groupName).toBe('install_methods-v2')
-  })
-  
-  test('group-name with invalid characters', async () => {
-    const div = page.locator('#group-name-invalid + div')
-    const groupName = await div.getAttribute('data-group-name')
-    // Should be rejected due to invalid characters
-    expect(groupName).toBeNull()
-  })
-})
-```
-
-**Test fixtures:** `/__tests__/e2e/markdown-extensions/index.md`
-
-Add new markdown sections:
-```markdown
-### Group Name Basic
-
-::: code-group group-name=installs
-
-```bash [npm]
-npm install vitepress
-```
-
-```bash [pnpm]
-pnpm add vitepress
-```
-
-:::
-
-### Group Name Quoted (Should be Rejected)
-
-::: code-group group-name="install methods"
-
-```bash [npm]
-npm install vitepress
-```
-
-```bash [yarn]
-yarn add vitepress
-```
-
-:::
-
-### Group Name with Hyphens and Underscores
-
-::: code-group group-name=install_methods-v2
-
-```bash [npm]
-npm install vitepress@next
-```
-
-```bash [pnpm]
-pnpm add vitepress@next
-```
-
-:::
-
-### Group Name Invalid Characters (Should be Rejected)
-
-::: code-group group-name=install@methods!
-
-```bash [npm]
-npm install vitepress
-```
-
-```bash [pnpm]
-pnpm add vitepress
-```
-
-:::
-```
-
-### 3. Manual Testing Checklist
-
-- [ ] Code group renders correctly in dev mode
-- [ ] Code group renders correctly in build mode
-- [ ] Tab switching works with group-name attribute
-- [ ] Multiple code groups on same page work independently
-- [ ] Code groups with same group-name attribute render correctly
-- [ ] Group name with hyphens works
-- [ ] Group name with underscores works
-- [ ] Group name with spaces is rejected (no attribute added)
-- [ ] Group name with invalid characters is rejected
-- [ ] Code group without group-name still works (backward compatibility)
-- [ ] Imported snippets work with group-name
-- [ ] Hot module reload works in dev mode
-
-## Documentation Updates
-
-### 1. Main Documentation
-
-**File:** `/docs/en/guide/markdown.md`
-
-**Section:** Code Groups (around line 690)
-
-**Addition:**
-
-```markdown
-### Named Code Groups
-
-You can optionally name code groups using the `group-name` parameter. This can be useful for semantic identification and potential future features like syncing tab selections across groups.
-
-**Input**
-
-````md
-::: code-group group-name=package-managers
-
-```bash [npm]
-npm install vitepress
-```
-
-```bash [pnpm]
-pnpm add vitepress
-```
-
-```bash [yarn]
-yarn add vitepress
-```
-
-:::
-````
-
-**Output**
-
-::: code-group group-name=package-managers
-
-```bash [npm]
-npm install vitepress
-```
-
-```bash [pnpm]
-pnpm add vitepress
-```
-
-```bash [yarn]
-yarn add vitepress
-```
-
-:::
-
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
-
-Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
-
-::: tip
-Named code groups add a `data-group-name` attribute to the generated HTML, which can be useful for custom styling or scripting.
-:::
-```
-
-### 2. API/Reference Documentation
-
-**File:** `/docs/en/reference/default-theme-config.md` or appropriate reference doc
-
-**If applicable:** Document the HTML structure and data attributes
-
-### 3. Internationalization
-
-Update the following language versions with translated content:
-- `/docs/es/guide/markdown.md`
-- `/docs/ja/guide/markdown.md`
-- `/docs/ko/guide/markdown.md`
-- `/docs/pt/guide/markdown.md`
-- `/docs/ru/guide/markdown.md`
-- `/docs/zh/guide/markdown.md`
-- `/docs/fa/guide/markdown.md`
-
-**Note:** Initial PR can focus on English docs, with i18n as follow-up PRs.
-
-## Migration & Backward Compatibility
-
-### Breaking Changes
-**None.** This is a purely additive feature.
-
-### Backward Compatibility
-- All existing code groups without `group-name` parameter continue to work exactly as before
-- The parameter is optional and doesn't change default behavior
-- No configuration changes required
-
-## Future Enhancements (Out of Scope for Initial PR)
-
-1. **Tab Synchronization**
-   - Sync tab selection across all code groups with the same `group-name`
-   - Example: Selecting "npm" in one "package-managers" group auto-selects "npm" in all other "package-managers" groups
-
-2. **LocalStorage Persistence**
-   - Remember user's last selected tab per group-name
-   - Restore selection on page load/navigation
-
-3. **Custom Styling Hooks**
-   - CSS variables for group-specific styling
-   - Example: Different color schemes per group-name
-
-4. **Programmatic API**
-   - JavaScript API to control code group tab selection
-   - Events for tab changes
-
-## Implementation Timeline
-
-1. **Phase 1:** Core implementation (containers.ts)
-2. **Phase 2:** Testing (unit + e2e)
-3. **Phase 3:** Documentation (English)
-4. **Phase 4:** Code review and refinement
-5. **Phase 5:** i18n documentation (can be separate PRs)
-
-## Files to Modify
-
-### Required Changes
-- ✅ `/src/node/markdown/plugins/containers.ts` - Core logic
-- ✅ `/__tests__/e2e/markdown-extensions/index.md` - Test fixtures
-- ✅ `/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts` - E2E tests
-- ✅ `/docs/en/guide/markdown.md` - Documentation
-
-### Optional/Future
-- ⏭️ `/src/client/app/composables/codeGroups.ts` - Tab sync feature
-- ⏭️ All i18n documentation files
-
-## Success Criteria
-
-- [ ] Group-name parameter is correctly parsed from markdown
-- [ ] HTML output includes `data-group-name` attribute when specified
-- [ ] All tests pass (existing + new)
-- [ ] Documentation is clear and includes examples
-- [ ] No regression in existing code group functionality
-- [ ] Code follows VitePress contribution guidelines
-- [ ] Commit messages follow convention
-
-## Notes
-
-- Keep the implementation simple and focused for the initial version
-- Ensure proper HTML escaping to prevent XSS vulnerabilities
-- Consider edge cases in parsing (quotes, special chars, etc.)
-- Maintain consistency with existing VitePress container syntax patterns

From 3641e70c30a1bac2b5c515242e2ea2f399d86c91 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 23:00:19 +0700
Subject: [PATCH 06/13] docs: add named code groups to all languages (pending
 translation)

---
 docs/es/guide/markdown.md | 96 +++++++++++++++++++++++++++++++++++++++
 docs/fa/guide/markdown.md | 96 +++++++++++++++++++++++++++++++++++++++
 docs/ja/guide/markdown.md | 96 +++++++++++++++++++++++++++++++++++++++
 docs/ko/guide/markdown.md | 96 +++++++++++++++++++++++++++++++++++++++
 docs/pt/guide/markdown.md | 96 +++++++++++++++++++++++++++++++++++++++
 docs/ru/guide/markdown.md | 96 +++++++++++++++++++++++++++++++++++++++
 docs/zh/guide/markdown.md | 96 +++++++++++++++++++++++++++++++++++++++
 7 files changed, 672 insertions(+)

diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index ebbd0d5e6b77..cc3fb4ae0e12 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -756,6 +756,102 @@ También puede [importar _snippets_ de código](#import-code-snippets) en grupos
 
 :::
 
+<!-- TODO: Translate to Spanish -->
+### Named Code Groups
+
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+<!-- Later in the same page: -->
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+````
+
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
+:::
+<!-- END TODO: Translate to Spanish -->
+
 ## Inclusión de Archivo Markdown {#markdown-file-inclusion}
 
 Puede incluir un archivo markdown en otro archvo markdown, incluso anidado.
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index 4e17bd312e5e..3a5a3b08a9cb 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -707,6 +707,102 @@ export default config
 <<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [قطعه با منطقه]
 :::
 
+<!-- TODO: Translate to Farsi -->
+### Named Code Groups
+
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+<!-- Later in the same page: -->
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+````
+
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
+:::
+<!-- END TODO: Translate to Farsi -->
+
 ## ادغام فایل‌های Markdown {#markdown-file-inclusion}
 
 می‌توانید یک فایل Markdown را در یک فایل Markdown دیگر، حتی در صورت وجود تو در تو، وارد کنید.
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index 966ce72c8d2c..df1bcba942dc 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -781,6 +781,102 @@ export default {
 
 :::
 
+<!-- TODO: Translate to Japanese -->
+### Named Code Groups
+
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+<!-- Later in the same page: -->
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+````
+
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
+:::
+<!-- END TODO: Translate to Japanese -->
+
 ## Markdown ファイルのインクルード {#markdown-file-inclusion}
 
 ある Markdown ファイルの中に、別の Markdown ファイルを取り込めます（入れ子も可能）。
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index f2003ca61b97..9de8cf837fc7 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -754,6 +754,102 @@ export default config
 
 :::
 
+<!-- TODO: Translate to Korean -->
+### Named Code Groups
+
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+<!-- Later in the same page: -->
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+````
+
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
+:::
+<!-- END TODO: Translate to Korean -->
+
 ## 마크다운 파일 포함 {#markdown-file-inclusion}
 
 마크다운 파일을 다른 마크다운 파일에 포함시킬 수 있으며, 중첩도 가능합니다.
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index c41862706c29..f38ffb7ae369 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -754,6 +754,102 @@ Você também pode [importar _snippets_ de código](#import-code-snippets) em gr
 
 :::
 
+<!-- TODO: Translate to Portuguese -->
+### Named Code Groups
+
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+<!-- Later in the same page: -->
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+````
+
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
+:::
+<!-- END TODO: Translate to Portuguese -->
+
 ## Inclusão de Arquivo Markdown {#markdown-file-inclusion}
 
 Você pode incluir um arquivo markdown em outro arquivo markdown, mesmo aninhado.
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index 2bd1a5c1649d..445b20fdd0b1 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -778,6 +778,102 @@ export default config
 
 :::
 
+<!-- TODO: Translate to Russian -->
+### Named Code Groups
+
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+<!-- Later in the same page: -->
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+````
+
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
+:::
+<!-- END TODO: Translate to Russian -->
+
 ## Включение файла Markdown {#markdown-file-inclusion}
 
 Вы можете включить файл Markdown в другой файл Markdown, даже вложенный.
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index a401774ccfd4..18aaaa47128e 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -754,6 +754,102 @@ export default config
 
 :::
 
+<!-- TODO: Translate to Chinese -->
+### Named Code Groups
+
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+
+**Input**
+
+````md
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+<!-- Later in the same page: -->
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+````
+
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+
+**Output**
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm install vitepress
+```
+
+```bash [pnpm]
+pnpm add vitepress
+```
+
+```bash [yarn]
+yarn add vitepress
+```
+
+:::
+
+::: code-group group-name=package-managers
+
+```bash [npm]
+npm run docs
+```
+
+```bash [pnpm]
+pnpm run docs
+```
+
+```bash [yarn]
+yarn docs
+```
+
+:::
+
+::: tip
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+:::
+
+The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+
+Valid examples:
+- `group-name=installs`
+- `group-name=install-methods`
+- `group-name=install_methods`
+- `group-name=installMethods`
+
+::: tip
+This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
+:::
+<!-- END TODO: Translate to Chinese -->
+
 ## 包含 markdown 文件 {#markdown-file-inclusion}
 
 可以像这样在一个 markdown 文件中包含另一个 markdown 文件，甚至是内嵌的。

From aafc201c41ebdd63861bdaa6379f6eda9d8747f2 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 23:14:10 +0700
Subject: [PATCH 07/13] feat: add localStorage persistence for named code
 groups

---
 .../markdown-extensions.test.ts               |  5 ++
 docs/en/guide/markdown.md                     |  4 ++
 src/client/app/composables/codeGroups.ts      | 58 ++++++++++++++++++-
 3 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts b/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
index 312eef77da7f..656b669e0686 100644
--- a/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
+++ b/__tests__/e2e/markdown-extensions/markdown-extensions.test.ts
@@ -301,6 +301,11 @@ describe('Code Groups', () => {
   })
 
   test('group-name synchronization across groups', async () => {
+    // Clear localStorage to ensure clean test state
+    await page.evaluate(() => localStorage.clear())
+    await page.reload()
+    await page.waitForSelector('#group-name-basic + div')
+
     const div1 = page.locator('#group-name-basic + div')
     const div2 = page.locator(
       '#group-name-second-instance-same-name-for-sync-test + div'
diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index 99ea3dbd28d0..d11bb6e5929a 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -858,6 +858,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
diff --git a/src/client/app/composables/codeGroups.ts b/src/client/app/composables/codeGroups.ts
index e01a25845d71..5d57d6ad7397 100644
--- a/src/client/app/composables/codeGroups.ts
+++ b/src/client/app/composables/codeGroups.ts
@@ -1,5 +1,28 @@
 import { inBrowser, onContentUpdated } from 'vitepress'
 
+const STORAGE_KEY = 'vitepress:tabsCache'
+
+function getStoredTabIndex(groupName: string): number | null {
+  if (!inBrowser) return null
+  try {
+    const cache = JSON.parse(localStorage.getItem(STORAGE_KEY) || '{}')
+    return cache[groupName] ?? null
+  } catch {
+    return null
+  }
+}
+
+function setStoredTabIndex(groupName: string, index: number) {
+  if (!inBrowser) return
+  try {
+    const cache = JSON.parse(localStorage.getItem(STORAGE_KEY) || '{}')
+    cache[groupName] = index
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(cache))
+  } catch {
+    // Silently ignore localStorage errors
+  }
+}
+
 export function useCodeGroups() {
   if (import.meta.env.DEV) {
     onContentUpdated(() => {
@@ -13,6 +36,38 @@ export function useCodeGroups() {
   }
 
   if (inBrowser) {
+    // Restore tabs from localStorage on page load, but only on first content load
+    let hasRestoredTabs = false
+    onContentUpdated(() => {
+      if (hasRestoredTabs) return
+      hasRestoredTabs = true
+
+      document
+        .querySelectorAll('.vp-code-group[data-group-name]')
+        .forEach((group) => {
+          const groupName = group.getAttribute('data-group-name')
+          if (!groupName) return
+
+          const storedIndex = getStoredTabIndex(groupName)
+          if (storedIndex === null) return
+
+          const inputs = group.querySelectorAll('input')
+          const blocks = group.querySelector('.blocks')
+          if (!blocks || !inputs[storedIndex]) return
+
+          // Update radio input
+          inputs[storedIndex].checked = true
+
+          // Update active block
+          const currentActive = blocks.querySelector('.active')
+          const newActive = blocks.children[storedIndex]
+          if (currentActive && newActive && currentActive !== newActive) {
+            currentActive.classList.remove('active')
+            newActive.classList.add('active')
+          }
+        })
+    })
+
     window.addEventListener('click', (e) => {
       const el = e.target as HTMLInputElement
 
@@ -42,9 +97,10 @@ export function useCodeGroups() {
         const label = group?.querySelector(`label[for="${el.id}"]`)
         label?.scrollIntoView({ block: 'nearest' })
 
-        // Sync other groups with same group-name
+        // Sync other groups with same group-name and save to localStorage
         const groupName = group.getAttribute('data-group-name')
         if (groupName) {
+          setStoredTabIndex(groupName, i)
           syncTabsInOtherGroups(groupName, i, group as HTMLElement)
         }
       }

From 44a9622354b40e6cd444d10bd9bbd94a2b9d2b7a Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Sun, 2 Nov 2025 23:25:11 +0700
Subject: [PATCH 08/13] docs: sync all languages with localStorage persistence
 info

---
 docs/es/guide/markdown.md | 4 ++++
 docs/fa/guide/markdown.md | 4 ++++
 docs/ja/guide/markdown.md | 4 ++++
 docs/ko/guide/markdown.md | 4 ++++
 docs/pt/guide/markdown.md | 4 ++++
 docs/ru/guide/markdown.md | 4 ++++
 docs/zh/guide/markdown.md | 4 ++++
 7 files changed, 28 insertions(+)

diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index cc3fb4ae0e12..3289c315c7a8 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -839,6 +839,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index 3a5a3b08a9cb..78a592b57abe 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -790,6 +790,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index df1bcba942dc..c616217b413f 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -864,6 +864,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index 9de8cf837fc7..2643c0db8a4d 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -837,6 +837,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index f38ffb7ae369..f7cd83e7610d 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -837,6 +837,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index 445b20fdd0b1..a07dc2b7556c 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -861,6 +861,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index 18aaaa47128e..eb7e1980c178 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -837,6 +837,10 @@ yarn docs
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
 :::
 
+::: info
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+:::
+
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:

From f1f7d880ae94267f5d684141c3b9e18539f84c42 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Mon, 3 Nov 2025 00:04:02 +0700
Subject: [PATCH 09/13] docs: clarify that tab sync works across domain, not
 just page

---
 docs/en/guide/markdown.md | 2 +-
 docs/es/guide/markdown.md | 2 +-
 docs/fa/guide/markdown.md | 2 +-
 docs/ja/guide/markdown.md | 2 +-
 docs/ko/guide/markdown.md | 2 +-
 docs/pt/guide/markdown.md | 2 +-
 docs/ru/guide/markdown.md | 2 +-
 docs/zh/guide/markdown.md | 2 +-
 8 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index d11bb6e5929a..4ab669dad195 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -799,7 +799,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 
diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index 3289c315c7a8..8a331cc78f64 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -780,7 +780,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index 78a592b57abe..6cdb172b3e89 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -731,7 +731,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index c616217b413f..752a6804e2e5 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -805,7 +805,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index 2643c0db8a4d..8f795ee95bc0 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -778,7 +778,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index f7cd83e7610d..a44ec4cc005d 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -778,7 +778,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index a07dc2b7556c..6b71d4e7b7a0 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -802,7 +802,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index eb7e1980c178..60d34828b75b 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -778,7 +778,7 @@ yarn add vitepress
 
 :::
 
-<!-- Later in the same page: -->
+<!-- Later in the same domain: -->
 
 ::: code-group group-name=package-managers
 

From 88726b3ec43ce6bd29741f121bd6d9fcf44e1edd Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Mon, 3 Nov 2025 00:25:23 +0700
Subject: [PATCH 10/13] refactor: rename group-name parameter to name

---
 __tests__/e2e/markdown-extensions/index.md | 10 ++++-----
 docs/en/guide/markdown.md                  | 24 +++++++++++-----------
 docs/es/guide/markdown.md                  | 18 ++++++++--------
 docs/fa/guide/markdown.md                  | 18 ++++++++--------
 docs/ja/guide/markdown.md                  | 18 ++++++++--------
 docs/ko/guide/markdown.md                  | 18 ++++++++--------
 docs/pt/guide/markdown.md                  | 18 ++++++++--------
 docs/ru/guide/markdown.md                  | 18 ++++++++--------
 docs/zh/guide/markdown.md                  | 18 ++++++++--------
 src/node/markdown/plugins/containers.ts    | 16 +++++++--------
 10 files changed, 88 insertions(+), 88 deletions(-)

diff --git a/__tests__/e2e/markdown-extensions/index.md b/__tests__/e2e/markdown-extensions/index.md
index af2843bd249d..f57f20e1ac1f 100644
--- a/__tests__/e2e/markdown-extensions/index.md
+++ b/__tests__/e2e/markdown-extensions/index.md
@@ -175,7 +175,7 @@ export default config
 
 ### Group Name Basic
 
-::: code-group group-name=installs
+::: code-group name=installs
 
 ```bash [npm]
 npm install vitepress
@@ -189,7 +189,7 @@ pnpm add vitepress
 
 ### Group Name Second Instance (Same Name for Sync Test)
 
-::: code-group group-name=installs
+::: code-group name=installs
 
 ```bash [npm]
 npm run docs
@@ -203,7 +203,7 @@ pnpm run docs
 
 ### Group Name with Hyphens and Underscores
 
-::: code-group group-name=install_methods-v2
+::: code-group name=install_methods-v2
 
 ```bash [npm]
 npm install vitepress@next
@@ -217,7 +217,7 @@ pnpm add vitepress@next
 
 ### Group Name with Spaces (Should be Rejected)
 
-::: code-group group-name="install methods"
+::: code-group name="install methods"
 
 ```bash [npm]
 npm install vitepress
@@ -231,7 +231,7 @@ yarn add vitepress
 
 ### Group Name with Invalid Characters (Should be Rejected)
 
-::: code-group group-name=install@methods!
+::: code-group name=install@methods!
 
 ```bash [npm]
 npm install vitepress
diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index 4ab669dad195..dbbb90e50c37 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -783,7 +783,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -801,7 +801,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -818,11 +818,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -838,7 +838,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -855,20 +855,20 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index 8a331cc78f64..63e50ccfe2ce 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -764,7 +764,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -782,7 +782,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -799,11 +799,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -819,7 +819,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -846,10 +846,10 @@ Your tab selection is automatically saved to localStorage. When you return to th
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index 6cdb172b3e89..2184c82a8d2c 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -715,7 +715,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -733,7 +733,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -750,11 +750,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -770,7 +770,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -797,10 +797,10 @@ Your tab selection is automatically saved to localStorage. When you return to th
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index 752a6804e2e5..8f65f0ac879e 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -789,7 +789,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -807,7 +807,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -824,11 +824,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -844,7 +844,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -871,10 +871,10 @@ Your tab selection is automatically saved to localStorage. When you return to th
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index 8f795ee95bc0..0654d7707bfc 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -762,7 +762,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -780,7 +780,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -797,11 +797,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -817,7 +817,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -844,10 +844,10 @@ Your tab selection is automatically saved to localStorage. When you return to th
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index a44ec4cc005d..93ba5581bbf2 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -762,7 +762,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -780,7 +780,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -797,11 +797,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -817,7 +817,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -844,10 +844,10 @@ Your tab selection is automatically saved to localStorage. When you return to th
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index 6b71d4e7b7a0..628c785ab70c 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -786,7 +786,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -804,7 +804,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -821,11 +821,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -841,7 +841,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -868,10 +868,10 @@ Your tab selection is automatically saved to localStorage. When you return to th
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index 60d34828b75b..d2aeb9ccff30 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -762,7 +762,7 @@ You can name code groups to synchronize tab selections across multiple groups. W
 **Input**
 
 ````md
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -780,7 +780,7 @@ yarn add vitepress
 
 <!-- Later in the same domain: -->
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -797,11 +797,11 @@ yarn docs
 :::
 ````
 
-When you click on a tab (e.g., "pnpm") in one group, all other groups with `group-name=package-managers` will automatically switch to the same tab.
+When you click on a tab (e.g., "pnpm") in one group, all other groups with `name=package-managers` will automatically switch to the same tab.
 
 **Output**
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm install vitepress
@@ -817,7 +817,7 @@ yarn add vitepress
 
 :::
 
-::: code-group group-name=package-managers
+::: code-group name=package-managers
 
 ```bash [npm]
 npm run docs
@@ -844,10 +844,10 @@ Your tab selection is automatically saved to localStorage. When you return to th
 The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
-- `group-name=installs`
-- `group-name=install-methods`
-- `group-name=install_methods`
-- `group-name=installMethods`
+- `name=installs`
+- `name=install-methods`
+- `name=install_methods`
+- `name=installMethods`
 
 ::: tip
 This feature is especially useful in documentation where you show the same tool (like package managers or programming languages) in multiple places, providing a consistent experience for users.
diff --git a/src/node/markdown/plugins/containers.ts b/src/node/markdown/plugins/containers.ts
index d4e3b8152ebc..c79924a9b315 100644
--- a/src/node/markdown/plugins/containers.ts
+++ b/src/node/markdown/plugins/containers.ts
@@ -67,18 +67,18 @@ function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
           const token = tokens[idx]
           const info = token.info.trim()
 
-          // Extract group-name parameter
-          const groupNameMatch = info.match(/group-name=(\S+)/)
-          let groupName = groupNameMatch ? groupNameMatch[1] : null
+          // Extract name parameter
+          const nameMatch = info.match(/name=(\S+)/)
+          let name = nameMatch ? nameMatch[1] : null
 
           // Validate: only allow alphanumeric, hyphens, and underscores
-          if (groupName && !/^[a-zA-Z0-9_-]+$/.test(groupName)) {
-            groupName = null
+          if (name && !/^[a-zA-Z0-9_-]+$/.test(name)) {
+            name = null
           }
 
           // Build data attribute
-          const groupNameAttr = groupName
-            ? ` data-group-name="${md.utils.escapeHtml(groupName)}"`
+          const nameAttr = name
+            ? ` data-group-name="${md.utils.escapeHtml(name)}"`
             : ''
 
           let tabs = ''
@@ -112,7 +112,7 @@ function createCodeGroup(md: MarkdownItAsync): ContainerArgs {
             }
           }
 
-          return `<div class="vp-code-group"${groupNameAttr}><div class="tabs">${tabs}</div><div class="blocks">\n`
+          return `<div class="vp-code-group"${nameAttr}><div class="tabs">${tabs}</div><div class="blocks">\n`
         }
         return `</div></div>\n`
       }

From bb186da63ee43c3d1bbb46c384f0b4c5aef12e5f Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Mon, 3 Nov 2025 00:33:24 +0700
Subject: [PATCH 11/13] docs: update remaining group-name references to name in
 all languages

---
 docs/es/guide/markdown.md | 6 +++---
 docs/fa/guide/markdown.md | 6 +++---
 docs/ja/guide/markdown.md | 6 +++---
 docs/ko/guide/markdown.md | 6 +++---
 docs/pt/guide/markdown.md | 6 +++---
 docs/ru/guide/markdown.md | 6 +++---
 docs/zh/guide/markdown.md | 6 +++---
 7 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index 63e50ccfe2ce..3acd0929cfc5 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -836,14 +836,14 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
 - `name=installs`
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index 2184c82a8d2c..ae5974101d34 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -787,14 +787,14 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
 - `name=installs`
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index 8f65f0ac879e..eff19c1904af 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -861,14 +861,14 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
 - `name=installs`
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index 0654d7707bfc..43ada2c2645b 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -834,14 +834,14 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
 - `name=installs`
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index 93ba5581bbf2..1fdd26c74aa8 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -834,14 +834,14 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
 - `name=installs`
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index 628c785ab70c..8ed8f0f3a1c8 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -858,14 +858,14 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
 - `name=installs`
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index d2aeb9ccff30..7accb97aadd7 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -834,14 +834,14 @@ yarn docs
 :::
 
 ::: tip
-Try clicking different tabs above! Notice how both code groups switch together because they share the same `group-name`.
+Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
 :::
 
 ::: info
-Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each group-name will be automatically selected.
+Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
 :::
 
-The `group-name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
+The `name` parameter accepts only alphanumeric characters, hyphens, and underscores. No whitespace is allowed.
 
 Valid examples:
 - `name=installs`

From bad02467db83831f45e32ed9fe3a1319c300973e Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Mon, 3 Nov 2025 00:35:37 +0700
Subject: [PATCH 12/13] docs: remove tip box around tab switching instruction

---
 docs/en/guide/markdown.md | 2 --
 docs/es/guide/markdown.md | 2 --
 docs/fa/guide/markdown.md | 2 --
 docs/ja/guide/markdown.md | 2 --
 docs/ko/guide/markdown.md | 2 --
 docs/pt/guide/markdown.md | 2 --
 docs/ru/guide/markdown.md | 2 --
 docs/zh/guide/markdown.md | 2 --
 8 files changed, 16 deletions(-)

diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index dbbb90e50c37..90185977b147 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -854,9 +854,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index 3acd0929cfc5..10ad39d3970b 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -835,9 +835,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index ae5974101d34..580fd387d656 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -786,9 +786,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index eff19c1904af..667946ae39f9 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -860,9 +860,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index 43ada2c2645b..7c93a6040e4a 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -833,9 +833,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index 1fdd26c74aa8..86d033744829 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -833,9 +833,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index 8ed8f0f3a1c8..a83d4d234250 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -857,9 +857,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index 7accb97aadd7..b5e4c8bf9847 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -833,9 +833,7 @@ yarn docs
 
 :::
 
-::: tip
 Try clicking different tabs above! Notice how both code groups switch together because they share the same `name`.
-:::
 
 ::: info
 Your tab selection is automatically saved to localStorage. When you return to the page, your preferred tab for each name will be automatically selected.

From 64d51485d3cbe79d4b1acca2aa07e61444254c82 Mon Sep 17 00:00:00 2001
From: juji <jujiyangasli@gmail.com>
Date: Mon, 3 Nov 2025 01:01:17 +0700
Subject: [PATCH 13/13] docs: remove 'on a page' from Named Code Groups
 description

---
 docs/en/guide/markdown.md | 2 +-
 docs/es/guide/markdown.md | 2 +-
 docs/fa/guide/markdown.md | 2 +-
 docs/ja/guide/markdown.md | 2 +-
 docs/ko/guide/markdown.md | 2 +-
 docs/pt/guide/markdown.md | 2 +-
 docs/ru/guide/markdown.md | 2 +-
 docs/zh/guide/markdown.md | 2 +-
 8 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index 90185977b147..fcba9834449a 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -778,7 +778,7 @@ You can also [import snippets](#import-code-snippets) in code groups:
 
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index 10ad39d3970b..b436354a67aa 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -759,7 +759,7 @@ También puede [importar _snippets_ de código](#import-code-snippets) en grupos
 <!-- TODO: Translate to Spanish -->
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index 580fd387d656..616670d177cd 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -710,7 +710,7 @@ export default config
 <!-- TODO: Translate to Farsi -->
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index 667946ae39f9..cb6a91d04724 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -784,7 +784,7 @@ export default {
 <!-- TODO: Translate to Japanese -->
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index 7c93a6040e4a..9e786dcfd5ac 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -757,7 +757,7 @@ export default config
 <!-- TODO: Translate to Korean -->
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index 86d033744829..7e7abad2ea3e 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -757,7 +757,7 @@ Você também pode [importar _snippets_ de código](#import-code-snippets) em gr
 <!-- TODO: Translate to Portuguese -->
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index a83d4d234250..1595b568b170 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -781,7 +781,7 @@ export default config
 <!-- TODO: Translate to Russian -->
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**
 
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index b5e4c8bf9847..93fc190f64b8 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -757,7 +757,7 @@ export default config
 <!-- TODO: Translate to Chinese -->
 ### Named Code Groups
 
-You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name on a page, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
+You can name code groups to synchronize tab selections across multiple groups. When you have multiple code groups with the same name, selecting a tab in one will automatically select the corresponding tab in all other groups with the same name.
 
 **Input**