Fuwari 功能扩展：Code Group

给博客加了个代码组功能，类似 VitePress 的 code-groups，可以把多个代码块放在一起用 Tab 切换

效果#

1
Console.WriteLine("Hello");

1
Console.WriteLine("World");

1
print("Hello")

相同 tab 值的代码块会归到同一个 Tab 下，通过 sub-tab（文件名）切换

用法#

用 :::code-group 包裹代码块，每个代码块通过 tab 指定所属 Tab，title 指定文件名：

1
:::code-group
2

3
```cs tab="C#" title="Foo.cs"
4
Console.WriteLine("Hello");
5
```
6

7
```cs tab="C#" title="Bar.cs"
8
Console.WriteLine("World");
9
```
10

11
```py tab="Python" title="foo.py"
12
print("Hello")
13
```
14

15
:::

tab="..." — Tab 标签名，相同值的代码块归为一组
title="..." — 文件名，显示在 sub-tab 上（EC 原生属性）
不写 tab 时回退到语言名大写

实现#

整个功能涉及四个部分，走的是 SSR 优先 的路线——Tab 导航和面板结构全部在 rehype 阶段构建，客户端只负责点击切换

渲染管线：Markdown → remark-directive → rehype（构建结构）→ Expressive Code（渲染代码块）→ HTML

Rehype 插件#

:::code-group 由 remark-directive 解析为容器指令，在 rehype 阶段会变成 <code-group> 元素。用一个直接操作 HAST 的 rehype 插件把它改写成完整的 Tab 结构：

1
import { h } from "hastscript";
2
import { SKIP, visit } from "unist-util-visit";
3

4
function parseMeta(meta, key) {
5
    const match = meta?.match(new RegExp(`${key}="([^"]+)"`));
6
    return match ? match[1] : null;
7
}
8

9
export function rehypeCodeGroup() {
10
    return (tree) => {
11
        visit(tree, "element", (node) => {
12
            if (node.tagName !== "code-group") return;
13

14
            const codeBlocks = node.children
15
                .filter((c) => c.tagName === "pre");
16

17
            // 按 tab 值分组
18
            const tabOrder = [];
19
            const tabGroups = new Map();
20
            for (const pre of codeBlocks) {
21
                const code = pre.children
22
                    ?.find((c) => c.tagName === "code");
23
                const meta = code?.data?.meta || "";
24
                const tab = parseMeta(meta, "tab") || "Code";
25
                if (!tabGroups.has(tab)) {
26
                    tabOrder.push(tab);
27
                    tabGroups.set(tab, []);
28
                }
29
                tabGroups.get(tab).push({
30
                    pre,
31
                    title: parseMeta(meta, "title"),
32
                });
33
            }
34

35
            // 构建导航栏
36
            const nav = h("div", { className: ["code-group-nav"] },
37
                tabOrder.map((label, i) =>
38
                    h("button", {
39
                        className: ["code-group-tab",
40
                            ...(i === 0 ? ["active"] : [])],
41
                        "data-idx": String(i),
42
                        type: "button",
43
                    }, label)
44
                )
45
            );
46

47
            // 构建面板（含 sub-tab）
48
            const panels = [];
49
            tabOrder.forEach((label, ti) => {
50
                const items = tabGroups.get(label);
51
                if (items.length > 1 || items.some((i) => i.title)) {
52
                    // sub-nav
53
                    panels.push(h("div", {
54
                        className: ["code-group-sub-nav"],
55
                        "data-tab": String(ti),
56
                        style: ti !== 0 ? "display:none" : undefined,
57
                    }, items.map((item, si) =>
58
                        h("button", {
59
                            className: ["code-group-tab",
60
                                ...(si === 0 ? ["active"] : [])],
61
                            "data-idx": String(si),
62
                            type: "button",
63
                        }, item.title || `#${si + 1}`)
64
                    )));
65
                    items.forEach((item, si) => {
66
                        panels.push(h("div", {
67
                            className: ["code-group-panel"],
68
                            "data-tab": String(ti),
69
                            "data-sub": String(si),
70
                            style: ti !== 0 || si !== 0
71
                                ? "display:none" : undefined,
72
                        }, [item.pre]));
73
                    });
74
                } else {
75
                    panels.push(h("div", {
76
                        className: ["code-group-panel"],
77
                        "data-tab": String(ti),
78
                        style: ti !== 0 ? "display:none" : undefined,
79
                    }, [items[0].pre]));
80
                }
81
            });
82

83
            // 原地替换
84
            node.tagName = "div";
85
            node.properties = { className: ["code-group"] };
86
            node.children = [nav, ...panels];
87
            return SKIP;
88
        });
89
    };
90
}

关键点：

在 rehype 阶段 <pre><code> 还是原始状态，可以从 code.data.meta 读取 tab 和 title
用 h() 构建导航栏 + 面板结构，直接改写 node.tagName / node.children 就地替换
EC 的 rehype 插件在用户插件之后运行，会把 <pre> 替换成渲染后的代码块，但外层的 div.code-group-panel 等包装结构不受影响

在 astro.config.mjs 里注册为独立 rehype 插件：

1
import { rehypeCodeGroup } from "./src/plugins/rehype-code-group.mjs";
2

3
// rehypePlugins 数组
4
rehypePlugins: [
5
    rehypeCodeGroup,    // 在 rehype-components 之后
6
    // ...
7
]

Expressive Code 插件#

EC 不认识 tab 属性，会当作未知 meta 报错。写个插件在预处理阶段把它剥掉：

1
import { definePlugin } from "@expressive-code/core";
2

3
export function pluginCodeGroupTab() {
4
    return definePlugin({
5
        name: "Code Group Tab",
6
        hooks: {
7
            preprocessMetadata: (context) => {
8
                const meta = context.codeBlock.meta;
9
                const match = meta.match(/tab="([^"]+)"/);
10
                if (match) {
11
                    context.codeBlock.meta = meta
12
                        .replace(/tab="[^"]+"/, "").trim();
13
                }
14
            },
15
        },
16
    });
17
}

只做一件事：从 meta 中移除 tab="..."，让 EC 正常解析 title 等其他属性

客户端脚本#

结构已经在 rehype 阶段构建好了，客户端只需要一个全局 click 事件监听器处理 Tab 切换：

1
document.addEventListener("click", (e: MouseEvent) => {
2
    const btn = (e.target as Element | null)
3
        ?.closest(".code-group-tab") as HTMLElement | null;
4
    if (!btn) return;
5
    const nav = btn.parentElement as HTMLElement | null;
6
    const group = nav?.closest(".code-group") as HTMLElement | null;
7
    if (!group) return;
8

9
    const idx = btn.getAttribute("data-idx")!;
10

11
    // 切换 active 状态
12
    nav!.querySelectorAll(".code-group-tab")
13
        .forEach((t) => t.classList.remove("active"));
14
    btn.classList.add("active");
15

16
    if (nav!.classList.contains("code-group-nav")) {
17
        // 顶层 Tab：切换 sub-nav 和 panel 的显示
18
        group.querySelectorAll<HTMLElement>(
19
            ":scope > .code-group-sub-nav"
20
        ).forEach((sn) => {
21
            sn.style.display =
22
                sn.getAttribute("data-tab") === idx ? "" : "none";
23
        });
24
        group.querySelectorAll<HTMLElement>(
25
            ":scope > .code-group-panel"
26
        ).forEach((panel) => {
27
            if (panel.getAttribute("data-tab") !== idx) {
28
                panel.style.display = "none";
29
                return;
30
            }
31
            const sub = panel.getAttribute("data-sub");
32
            if (sub !== null) {
33
                const activeSub = group.querySelector(
34
                    `.code-group-sub-nav[data-tab="${idx}"] .active`
35
                )?.getAttribute("data-idx");
36
                panel.style.display =
37
                    sub === activeSub ? "" : "none";
38
            } else {
39
                panel.style.display = "";
40
            }
41
        });
42
    } else if (nav!.classList.contains("code-group-sub-nav")) {
43
        // Sub-tab：只切换同组面板
44
        const tabIdx = nav!.getAttribute("data-tab")!;
45
        group.querySelectorAll<HTMLElement>(
46
            `:scope > .code-group-panel[data-tab="${tabIdx}"]`
47
        ).forEach((panel) => {
48
            panel.style.display =
49
                panel.getAttribute("data-sub") === idx
50
                    ? "" : "none";
51
        });
52
    }
53
});

不需要 initCodeGroups 也不需要监听 Swup 的 page:view 事件——因为没有 DOM 构建，HTML 就绪即可用

样式#

Tab 导航栏的背景色复用了 EC 的 --codeblock-topbar-bg，保持视觉一致。code-group 内部的 EC 原生标题栏被隐藏（由自定义 Tab 导航替代），圆角也被重置为 0 交给外层容器统一处理