前言#

Expressive Code 提供与许多不同框架的集成，包括 Astro、Starlight、Next.js 以及任何支持 rehype 插件的框架。原生代码块的实用性不强，如没有折叠代码块、diff块复合语句和标签页功能等等，因此添加Expressive Code用于代码块渲染

Expressive Code 优点#

功能齐全：完整的 VS Code 主题支持、准确的语法突出显示、编辑器和终端框架、复制到剪贴板、文本标记、可折叠部分等
框架无关：不依赖 React、Vue 或任何其他前端框架。兼容 Astro 和 Next.js 等热门网站生成器，以及纯 Markdown 和 MDX
基于插件：全新构建，易于扩展。所有关键功能均已默认内置，并提供强大的 API 供您创建自己的插件
无障碍：设计时充分考虑了无障碍功能。自动确保合适的色彩对比度，并支持暗黑模式。兼容屏幕阅读器和键盘导航

引入 Expressive Code#

安装依赖#

切换到你的 Astro 站点根目录，在终端里安装astro-expressive-code

1
pnpm astro add astro-expressive-code
2
# 若需要手动更新到最新版本的话
3
pnpm add astro-expressive-code@latest

Astro 会提示你修改你的 astro.config.mjs 文件，一路按 y（yes）即可

修改文件#

添加依赖#

修改 package.json 文件（虽然我们在终端已经添加了依赖，但还有官方插件没有添加，所以我们手动添加依赖以及开发依赖）：

1
"dependencies": {
2
    "astro-expressive-code": "^0.41.2",
3
    "@expressive-code/core": "^0.41.2",
4
    "@expressive-code/plugin-collapsible-sections": "^0.41.2",
5
    "@expressive-code/plugin-line-numbers": "^0.41.2",
6
}
7

8
"devDependencies": {
9
    "@types/hast": "^3.0.4",
10
}

NOTE
分别添加核心，折叠与行号插件，还有更多插件可以去ec官网自行安装查看嗷点击跳转

CAUTION
修改完依赖后请务必在项目根目录终端运行 pnpm install 更新项目依赖，否则无法正常dev和build

注册并配置#

将 Expressive Code 深度集成到项目中就要修改 astro 的核心配置

1
// 添加插件和样式
2
import expressiveCode from "astro-expressive-code";
3
import { pluginCollapsibleSections } from "@expressive-code/plugin-collapsible-sections";
4
import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
5

6

7
import { expressiveCodeConfig } from "./src/config.ts";
8
import { pluginLanguageBadge } from "./src/plugins/expressive-code/language-badge.ts";
9

10
import { pluginCustomCopyButton } from "./src/plugins/expressive-code/custom-copy-button.js";

然后在 integrations 数组中找到astro帮助你添加的 expressiveCode() 方法在括号中添加以下内容主要对代码块的外观和行为进行修改:

themes: 设置代码块的主题。
plugins: 启用了行号、可折叠代码块、自定义语言徽章和自定义复制按钮等插件。
defaultProps: 设置了默认开启文本换行 (wrap: true)，并为特定语言（如 shellsession）覆盖默认行为（不显示行号）。
styleOverrides: 这是定制化的核心。它覆盖了默认样式，使用了项目的 CSS 变量（如 var(—codeblock-bg))，确保代码块风格与网站主题完美统一。从背景色、边框、字体，到编辑器标签栏、激活状态指示器颜色，都进行了精细调整。
frames: 隐藏了库自带的复制按钮，因为开发者通过插件实现了自定义的复制按钮。

1
        {
2
      themes: [expressiveCodeConfig.theme, expressiveCodeConfig.theme],
3
      plugins: [
4
        pluginCollapsibleSections(),
5
        pluginLineNumbers(),
6
        pluginLanguageBadge(),
7
        pluginCustomCopyButton()
8
      ],
9
      defaultProps: {
10
        wrap: true,
11
        overridesByLang: {
12
          'shellsession': {
13
            showLineNumbers: false,
14
          },
15
        },
16
      },
17
      styleOverrides: {
18
        codeBackground: "var(--codeblock-bg)",
19
        borderRadius: "0.75rem",
20
        borderColor: "none",
21
        codeFontSize: "0.875rem",
22
        codeFontFamily: "'JetBrains Mono Variable', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace",
23
        codeLineHeight: "1.5rem",
24
        frames: {
25
          editorBackground: "var(--codeblock-bg)",
26
          terminalBackground: "var(--codeblock-bg)",
27
          terminalTitlebarBackground: "var(--codeblock-topbar-bg)",
28
          editorTabBarBackground: "var(--codeblock-topbar-bg)",
29
          editorActiveTabBackground: "none",
30
          editorActiveTabIndicatorBottomColor: "var(--primary)",
31
          editorActiveTabIndicatorTopColor: "none",
32
          editorTabBarBorderBottomColor: "var(--codeblock-topbar-bg)",
33
          terminalTitlebarBorderBottomColor: "none"
34
        },
35
        textMarkers: {
36
          delHue: 0,
37
          insHue: 180,
38
          markHue: 250
39
        }
40
      },
41
      frames: {
42
        showCopyToClipboardButton: false,
43
      }
44
    }

1
//添加新配置格式
2
export type ExpressiveCodeConfig = {
3
  theme: string;
4
};

1
import { expressiveCodeConfig } from "@/config";

同文件下在 applyThemeToDocument 函数里添加:

1
export function applyThemeToDocument(theme: LIGHT_DARK_MODE) {
2
  switch (theme) {
3
    case LIGHT_MODE:
4
      document.documentElement.classList.remove("dark");
5
      break;
6
    case DARK_MODE:
7
      document.documentElement.classList.add("dark");
8
      break;
9
    case AUTO_MODE:
10
      if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
11
        document.documentElement.classList.add("dark");
12
      } else {
13
        document.documentElement.classList.remove("dark");
14
      }
15
      break;
16
  }
17

18
  // Set the theme for Expressive Code
19
  document.documentElement.setAttribute(
20
    "data-theme",
21
    expressiveCodeConfig.theme,
22
  );
23
}

更改布局#

更改 src\components\misc\Markdown.astro 布局文件的 <script> 标签：

1
<script>
2
document.addEventListener("click", function (e: MouseEvent) {
3
    const target = e.target as Element | null;
4
    if (target && target.classList.contains("copy-btn")) {
5
        const preEle = target.closest("pre");
6
        const codeEle = preEle?.querySelector("code");
7
        const code = Array.from(codeEle?.querySelectorAll(".code:not(summary *)") ?? [])
8
            .map(el => el.textContent)
9
            .map(t => t === "\n" ? "" : t)
10
            .join("\n");
11
        navigator.clipboard.writeText(code);
12

13
        const timeoutId = target.getAttribute("data-timeout-id");
14
        if (timeoutId) {
15
            clearTimeout(parseInt(timeoutId));
16
        }
17

18
        target.classList.add("success");
19

20
        // 设置新的timeout并保存ID到按钮的自定义属性中
21
        const newTimeoutId = setTimeout(() => {
22
            target.classList.remove("success");
23
        }, 1000);
24

25
        target.setAttribute("data-timeout-id", newTimeoutId.toString());
26
    }
27
});
28
</script>

删除 src/layouts/Layout.astro 文件的 preElements 常量

1
  const preElements = document.querySelectorAll('pre');
2
  preElements.forEach((ele) => {
3
    OverlayScrollbars(ele, {
4
      scrollbars: {
5
      theme: 'scrollbar-base scrollbar-dark px-2',
6
      autoHide: 'leave',
7
      autoHideDelay: 500,
8
      autoHideSuspend: false
9
    }
10
  });
11
});

添加组件#

添加以下文件：

1
import { definePlugin } from "@expressive-code/core";
2
import type { Element } from "hast";
3

4
export function pluginCustomCopyButton() {
5
  return definePlugin({
6
    name: "Custom Copy Button",
7
    hooks: {
8
      postprocessRenderedBlock: (context) => {
9
        function traverse(node: Element) {
10
          if (node.type === "element" && node.tagName === "pre") {
11
            processCodeBlock(node);
12
            return;
13
          }
14
          if (node.children) {
15
            for (const child of node.children) {
16
              if (child.type === "element") traverse(child);
17
            }
18
          }
19
        }
20

21
        function processCodeBlock(node: Element) {
22
          const copyButton = {
23
            type: "element" as const,
24
            tagName: "button",
25
            properties: {
26
              className: ["copy-btn"],
27
              "aria-label": "Copy code",
28
            },
29
            children: [
30
              {
31
                type: "element" as const,
32
                tagName: "div",
33
                properties: {
34
                  className: ["copy-btn-icon"],
35
                },
36
                children: [
37
                  {
38
                    type: "element" as const,
39
                    tagName: "svg",
40
                    properties: {
41
                      viewBox: "0 -960 960 960",
42
                      xmlns: "http://www.w3.org/2000/svg",
43
                      className: ["copy-btn-icon", "copy-icon"],
44
                    },
45
                    children: [
46
                      {
47
                        type: "element" as const,
48
                        tagName: "path",
49
                        properties: {
50
                          d: "M368.37-237.37q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-474.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26h378.26q34.48 0 58.74 24.26 24.26 24.26 24.26 58.74v474.26q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H368.37Zm0-83h378.26v-474.26H368.37v474.26Zm-155 238q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-515.76q0-17.45 11.96-29.48 11.97-12.02 29.33-12.02t29.54 12.02q12.17 12.03 12.17 29.48v515.76h419.76q17.45 0 29.48 11.96 12.02 11.97 12.02 29.33t-12.02 29.54q-12.03 12.17-29.48 12.17H213.37Zm155-238v-474.26 474.26Z",
51
                        },
52
                        children: [],
53
                      },
54
                    ],
55
                  },
56
                  {
57
                    type: "element" as const,
58
                    tagName: "svg",
59
                    properties: {
60
                      viewBox: "0 -960 960 960",
61
                      xmlns: "http://www.w3.org/2000/svg",
62
                      className: ["copy-btn-icon", "success-icon"],
63
                    },
64
                    children: [
65
                      {
66
                        type: "element" as const,
67
                        tagName: "path",
68
                        properties: {
69
                          d: "m389-377.13 294.7-294.7q12.58-12.67 29.52-12.67 16.93 0 29.61 12.67 12.67 12.68 12.67 29.53 0 16.86-12.28 29.14L419.07-288.41q-12.59 12.67-29.52 12.67-16.94 0-29.62-12.67L217.41-430.93q-12.67-12.68-12.79-29.45-.12-16.77 12.55-29.45 12.68-12.67 29.62-12.67 16.93 0 29.28 12.67L389-377.13Z",
70
                        },
71
                        children: [],
72
                      },
73
                    ],
74
                  },
75
                ],
76
              },
77
            ],
78
          } as Element;
79

80
          if (!node.children) {
81
            node.children = [];
82
          }
83
          node.children.push(copyButton);
84
        }
85

86
        traverse(context.renderData.blockAst);
87
      },
88
    },
89
  });
90
}

1
/**
2
 * Based on the discussion at https://github.com/expressive-code/expressive-code/issues/153#issuecomment-2282218684
3
 */
4
import { definePlugin } from "@expressive-code/core";
5

6
export function pluginLanguageBadge() {
7
  return definePlugin({
8
    name: "Language Badge",
9
    baseStyles: ({ cssVar }) => `
10
      [data-language]::before {
11
        position: absolute;
12
        z-index: 2;
13
        right: 0.5rem;
14
        top: 0.5rem;
15
        padding: 0.1rem 0.5rem;
16
        content: attr(data-language);
17
        font-size: 0.75rem;
18
        font-weight: bold;
19
        text-transform: uppercase;
20
        color: oklch(0.75 0.1 var(--hue));
21
        background: oklch(0.33 0.035 var(--hue));
22
        border-radius: 0.5rem;
23
        pointer-events: none;
24
        transition: opacity 0.3s;
25
        opacity: 0;
26
      }
27
      .frame:not(.has-title):not(.is-terminal) {
28
        @media (hover: none) {
29
          & [data-language]::before {
30
            opacity: 1;
31
            margin-right: 3rem;
32
          }
33
          & [data-language]:active::before {
34
            opacity: 0;
35
          }
36
        }
37
        @media (hover: hover) {
38
          & [data-language]::before {
39
            opacity: 1;
40
          }
41
          &:hover [data-language]::before {
42
            opacity: 0;
43
          }
44
        }
45
      }
46
    `,
47
  });
48
}

1
.expressive-code .frame {
2
  @apply !shadow-none;
3
}

删除原生代码自带的复制按钮样式：

1
 .copy-btn-icon {
2
     @apply absolute top-1/2 left-1/2 transition -translate-x-1/2 -translate-y-1/2
3
 }
4
 .copy-btn .copy-icon {
5
     @apply opacity-100 fill-white dark:fill-white/75
6
 }
7
 .copy-btn.success .copy-icon {
8
     @apply opacity-0 fill-[var(--deep-text)]
9
 }
10
.copy-btn .success-icon {
11
     @apply opacity-0
12
 }
13
 .copy-btn.success .success-icon {
14
     @apply opacity-100
15
 }

删除 markdown.css 中的 pre 样式并添加以下样式:

1
pre {
2
    @apply bg-[var(--codeblock-bg)] !important;
3
    @apply rounded-xl px-5;
4

5
    code {
6
        @apply bg-transparent text-inherit text-sm p-0;

1
    .copy-btn {
2
        all: initial;Add commentMore actions
3
        @apply btn-regular-dark opacity-0 shadow-lg shadow-black/50 absolute active:scale-90 h-8 w-8 top-3 right-3 text-sm rounded-lg transition-all ease-in-out z-20 cursor-pointer;
4
    }
5
    .frame:hover .copy-btn {
6
        opacity: 1;
7
    }
8

9
    .copy-btn-icon {
10
        @apply absolute top-1/2 left-1/2 transition -translate-x-1/2 -translate-y-1/2 w-4 h-4 fill-white pointer-events-none;
11
    }
12
    .copy-btn .copy-icon {
13
        @apply opacity-100 fill-white dark:fill-white/75;
14
    }
15
    .copy-btn.success .copy-icon {
16
        @apply opacity-0 fill-[var(--deep-text)]
17
    }
18
    .copy-btn .success-icon {
19
        @apply opacity-0 fill-white;
20
    }
21
    .copy-btn.success .success-icon {
22
        @apply opacity-100
23
    }
24

25
    .expressive-code {
26
        @apply my-4;
27
        ::selection {
28
            @apply bg-[var(--codeblock-selection)];

在 src/styles/variables.styl中修改

1
  --codeblock-bg: oklch(0.2 0.015 var(--hue)) oklch(0.17 0.015 var(--hue))
2

3
  --codeblock-bg: oklch(0.17 0.015 var(--hue)) oklch(0.17 0.015 var(--hue))
4
  --codeblock-topbar-bg: oklch(0.3 0.02 var(--hue)) oklch(0.12 0.015 var(--hue))

使用 Expressive Code#

Expressive Code