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 00000000..bbf05e45
--- /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 3446b4ef..7d19b49d 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 839f953c..3cbc5435 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 e1be3e6b..16c0b538 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 39efce17..d4e3b815 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 bbf05e45..b15a47a7 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 7d19b49d..af2843bd 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 3cbc5435..312eef77 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 16c0b538..ffbedf19 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 d8a38ba7..e01a2584 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 ffbedf19..cb982fa8 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 cb982fa8..99ea3dbd 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 b15a47a7..00000000
--- 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 ebbd0d5e..cc3fb4ae 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 4e17bd31..3a5a3b08 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 966ce72c..df1bcba9 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 f2003ca6..9de8cf83 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 c4186270..f38ffb7a 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 2bd1a5c1..445b20fd 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 a401774c..18aaaa47 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 312eef77..656b669e 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 99ea3dbd..d11bb6e5 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 e01a2584..5d57d6ad 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 cc3fb4ae..3289c315 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 3a5a3b08..78a592b5 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 df1bcba9..c616217b 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 9de8cf83..2643c0db 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 f38ffb7a..f7cd83e7 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 445b20fd..a07dc2b7 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 18aaaa47..eb7e1980 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 d11bb6e5..4ab669da 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 3289c315..8a331cc7 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 78a592b5..6cdb172b 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 c616217b..752a6804 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 2643c0db..8f795ee9 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 f7cd83e7..a44ec4cc 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 a07dc2b7..6b71d4e7 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 eb7e1980..60d34828 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 af2843bd..f57f20e1 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 4ab669da..dbbb90e5 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 8a331cc7..63e50ccf 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 6cdb172b..2184c82a 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 752a6804..8f65f0ac 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 8f795ee9..0654d770 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 a44ec4cc..93ba5581 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 6b71d4e7..628c785a 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 60d34828..d2aeb9cc 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 d4e3b815..c79924a9 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 63e50ccf..3acd0929 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 2184c82a..ae597410 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 8f65f0ac..eff19c19 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 0654d770..43ada2c2 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 93ba5581..1fdd26c7 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 628c785a..8ed8f0f3 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 d2aeb9cc..7accb97a 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 dbbb90e5..90185977 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 3acd0929..10ad39d3 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 ae597410..580fd387 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 eff19c19..667946ae 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 43ada2c2..7c93a604 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 1fdd26c7..86d03374 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 8ed8f0f3..a83d4d23 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 7accb97a..b5e4c8bf 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 90185977..fcba9834 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 10ad39d3..b436354a 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 580fd387..616670d1 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 667946ae..cb6a91d0 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 7c93a604..9e786dcf 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 86d03374..7e7abad2 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 a83d4d23..1595b568 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 b5e4c8bf..93fc190f 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**