Code Groups

Code groups display multiple code blocks as a tabbed interface with synced selection across groups. Each group uses the :::code-group container syntax and requires the Goldmark extension.

Basic code group

Wrap multiple fenced code blocks inside a :::code-group container:

1
:::code-group
2
3
```go title="main.go"
4
package main
5
6
import "fmt"
7
8
func main() {
9
    fmt.Println("Hello from Go!")
10
}

1
def main():
2
    print("Hello from Python!")
3
4
if __name__ == "__main__":
5
    main()

1
function main() {
2
  console.log("Hello from JavaScript!");
3
}
4
5
main();

:::

1
2
→ A tabbed interface with "main.go", "main.py", and "index.js" tabs. The first tab is active by default. Each panel contains a fully rendered Kazari code block with all features.
3
4
## Tab labels
5
6
Tab labels are derived in priority order:
7
8
| Priority | Source | Example |
9
|---|---|---|
10
| 1 | `title=` in the fence meta string | `title="main.go"` |
11
| 2 | File path comment in the first line | `// src/greet.js` |
12
| 3 | Capitalized language name | `go` becomes "Go" |
13
| 4 | Fallback | "Code" (when no language is set) |
14
15
File path comments follow the same extraction rules as [Frames & Titles](/features/frames-and-titles/). The comment line is removed from the rendered output.
16
17
## Tab sync
18
19
Add a `sync=` attribute to keep groups in sync. When a tab is selected in one group, the matching tab in all other groups with the same sync key is activated automatically:
20
21
```markdown
22
:::code-group sync="language"
23
24
```go
25
go get github.com/example/pkg

1
pip install example-pkg

:::

1
import "github.com/example/pkg"

1
import example_pkg

1
2
→ Selecting "Go" in the first group also selects "Go" in the second group.
3
4
Sync behavior:
5
6
- Tabs are matched by their exact label text, not by language identifier or tab index. Groups must use identical tab labels for sync to connect them.
7
- The active tab is persisted in `localStorage` per sync key and restored on page load.
8
- Groups with different sync keys sync independently.
9
- A group without `sync=` does not participate in syncing.
10
11
## Keyboard navigation
12
13
The tab bar follows the ARIA tab panel pattern:
14
15
| Key | Action |
16
|---|---|
17
| Arrow Right | Next tab (wraps to first) |
18
| Arrow Left | Previous tab (wraps to last) |
19
| Home | First tab |
20
| End | Last tab |
21
22
Tabs use the roving tabindex pattern: the active tab has `tabindex="0"`, all others have `tabindex="-1"`. ARIA IDs linking tabs to panels (`aria-controls`, `aria-labelledby`) are assigned client-side by JavaScript on page load.
23
24
## Goldmark setup
25
26
Register both the base code block renderer and the code group extension:
27
28
```go
29
md := goldmark.New(goldmark.WithExtensions(
30
    kazarimd.New(engine),
31
    kazarimd.CodeGroups(engine),
32
))

kazarimd.CodeGroups(engine) calls engine.EnableCodeGroups() internally. This must be called during setup, before the engine is used for concurrent rendering or before calling engine.CSS() and engine.JS(), so that the code group styles and scripts are included in the output.

There is no WithCodeGroups engine option and no config file equivalent. Code groups are enabled exclusively through the Goldmark extension.

Full setup details are on the Goldmark Extension page.

Per-block features

Each tab inside a code group is rendered through the normal RenderWithMeta pipeline. All Kazari features work per-tab: line numbers, markers, focus lines, collapsible sections, output panels, frame overrides, and theme overrides. Meta string options are set independently on each fenced code block within the group.

1
:::code-group
2
3
```go title="main.go" showLineNumbers {3-5}
4
package main
5
6
func main() {
7
    fmt.Println("Hello")
8
}

1
def main():
2
    print("Hello")

:::

1
2
## CSS variables
3
4
### Static variables
5
6
| Variable | Default | Description |
7
|---|---|---|
8
| `--kz-group-tab-bg` | `transparent` | Tab background |
9
| `--kz-group-tab-fg` | `inherit` | Tab text color |
10
| `--kz-group-tab-active-border` | `#007acc` | Active tab bottom border |
11
| `--kz-group-tab-padding` | `0.5rem 1rem` | Tab padding |
12
| `--kz-group-border-width` | `1px` | Group container border width |
13
| `--kz-group-radius` | `var(--kz-radius)` | Group container border radius |
14
15
### Luminance-derived variables
16
17
These values adapt automatically based on each theme's editor background brightness:
18
19
| Variable | Light theme | Dark theme |
20
|---|---|---|
21
| `--kz-group-tab-active-bg` | `rgba(255,255,255,0.8)` | `rgba(255,255,255,0.1)` |
22
| `--kz-group-tab-active-fg` | `#24292f` | `#e6edf3` |
23
| `--kz-group-border` | `rgba(0,0,0,0.1)` | `rgba(255,255,255,0.1)` |
24
25
These three variables have no built-in defaults at the `:root` level. They are computed per theme from the editor background luminance and emitted inside each theme's scoped CSS block.
26
27
All code group CSS variables are only emitted when `EnableCodeGroups()` has been called. See the [CSS Variables](/reference/css-variables/) reference for the complete list.
28
29
## Edge cases
30
31
- A group with no fenced code children renders nothing. Non-code content (paragraphs, headings) inside `:::code-group` is silently dropped.
32
- A single-block group renders the full tab/panel structure with one tab.
33
- Nested `:::code-group` containers are not supported. The inner directive is treated as text.
34
- Standalone code blocks outside groups render normally, independently.
35
- `aria-label="Code variants"` on the tab list is hardcoded English and is not localizable via `WithLocale` or `WithUIStrings`.
36
- Tab sync matches by label text only. If two synced groups use different labels for the same language (e.g., "Go" vs "main.go"), they will not sync with each other.
37
- There is no programmatic Go API for building code groups. Groups are created exclusively through the `:::code-group` Markdown syntax processed by the Goldmark extension.