1578 字
8 分钟
Fuwari 集成 Expressive Code 代码块 ~ 一种低侵略性、少量改动方法
2025-05-20
折腾
Fuwari
WARNING

Fuwari 官方已于 2025.06.03 支持 Expressive Code，故本文已归档，参考 Commit ee48c2f （官方目前仅支持暗色主题）

前言#

Fuwari 主题内置的代码块功能比较简陋，而 Expressive Code 提供了一个功能丰富，且视觉效果较好的解决方案，并且Expressive Code还官方的Astro框架集成，成为了Fuwari主题代码块增强的不二之选。

NOTE

经粗略测试，在集成Expressive Code基本功能后，会增加一个大小约为 4.4kB 的文件（没有代码块的文章不受影响），在添加代码行号和代码折叠插件后变为 5.6kB，请考虑是能够接受这一变化。

相关工作#

非常感谢伊卡和Hasenpfote的贡献，本文将在两位大佬的基础上作出一些微小的改动。如果您不需要这些改动，那么遵循伊卡的方法即可方便的集成Expressive Code。

伊卡在增强Fuwari的代码块功能中介绍了集成Expressive Code的基本方法，并且具有主题切换功能，但是对原有代码的侵略性较强，需要修改原始的主题切换逻辑，不便于后续维护以及与Fuwari的更新merge。

Hasenpfote在feat: improve code block feature with Expressive Code提出了一个较完善的Expressive Code集成方案，并且支持用户自定义主题的切换，但仍然具有侵略性。由于该PR未能合并到主干，部分代码不再具有时效性。例如Fuwari中已经移除了Compress集成。

本文概述#

本文基于伊卡和Hasenpfote两位大佬的方法，根据Expressive Code的themeCssSelector配置项，对主题切换的功能进行了改进，并尽可能以低侵略性、少量改动的方式集成Expressive Code。

成果展示请查看 Fuwari 博客特性展示

注释原始代码#

由于Fuwari的代码块实现会影响Expressive Code的集成，需要先注释掉原始的代码。以下代码的行号以及内容仅供参考，随着Fuwari的更新，实际的代码可能会有差异，请善用特征代码搜索。

src/components/misc/Markdown.astro
14 collapsed lines
---
import "@fontsource-variable/jetbrains-mono";
import "@fontsource-variable/jetbrains-mono/wght-italic.css";


interface Props {
  class: string;
}
const className = Astro.props.class;
---
<div data-pagefind-body class={`prose dark:prose-invert prose-base !max-w-none custom-md ${className}`}>
    <!--<div class="prose dark:prose-invert max-w-none custom-md">-->
    <!--<div class="max-w-none custom-md">-->
    <slot/>
</div>


<!-- 引入 expressiveCode，注释以下代码
<script>
  const observer = new MutationObserver(addPreCopyButton);
  observer.observe(document.body, { childList: true, subtree: true });
43 collapsed lines


  function addPreCopyButton() {
    observer.disconnect();


    let codeBlocks = Array.from(document.querySelectorAll("pre"));


    for (let codeBlock of codeBlocks) {
      if (codeBlock.parentElement?.nodeName === "DIV" && codeBlock.parentElement?.classList.contains("code-block")) continue


      let wrapper = document.createElement("div");
      wrapper.className = "relative code-block";


      let copyButton = document.createElement("button");
      copyButton.className = "copy-btn btn-regular-dark absolute active:scale-90 h-8 w-8 top-2 right-2 opacity-75 text-sm p-1.5 rounded-lg transition-all ease-in-out";


      codeBlock.setAttribute("tabindex", "0");
      if (codeBlock.parentNode) {
        codeBlock.parentNode.insertBefore(wrapper, codeBlock);
      }


      let copyIcon = `<svg class="copy-btn-icon copy-icon" xmlns="http://www.w3.org/2000/svg" height="20px" viewBox="0 -960 960 960" width="20px"><path 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"/></svg>`
      let successIcon = `<svg class="copy-btn-icon success-icon" xmlns="http://www.w3.org/2000/svg" height="20px" viewBox="0 -960 960 960" width="20px"><path 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"/></svg>`
      copyButton.innerHTML = `<div>${copyIcon} ${successIcon}</div>
      `


      wrapper.appendChild(codeBlock);
      wrapper.appendChild(copyButton);


      let timeout: ReturnType<typeof setTimeout>;
      copyButton.addEventListener("click", async () => {
        if (timeout) {
            clearTimeout(timeout);
        }
        let text = codeBlock?.querySelector("code")?.innerText;
        if (text === undefined) return;
        await navigator.clipboard.writeText(text);
        copyButton.classList.add("success");
        timeout = setTimeout(() => {
          copyButton.classList.remove("success");
        }, 1000);
      });
    }


    observer.observe(document.body, { childList: true, subtree: true });
  }
</script>
 -->

然后注释掉pre标签的样式。

src/layouts/Layout.astro
 /* 引入 expressiveCode，注释以下代码
const preElements = document.querySelectorAll('pre');
preElements.forEach((ele) => {
  OverlayScrollbars(ele, {
    scrollbars: {
      theme: 'scrollbar-base scrollbar-dark px-2',
      autoHide: 'leave',
      autoHideDelay: 500,
      autoHideSuspend: false
    }
  });
});
 */
src/styles/main.css
 /* 引入 expressiveCode，注释以下代码
.copy-btn-icon {
    @apply absolute top-1/2 left-1/2 transition -translate-x-1/2 -translate-y-1/2
}
.copy-btn .copy-icon {
    @apply opacity-100 fill-white dark:fill-white/75
}
.copy-btn.success .copy-icon {
    @apply opacity-0 fill-[var(--deep-text)]
}
.copy-btn .success-icon {
    @apply opacity-0
}
.copy-btn.success .success-icon {
    @apply opacity-100
}
 */

markdown.css 在注释相关代码之后建议添加一个样式，用于在代码块底部添加margin，避免连续的代码块之间紧挨，以及代码块与标题紧挨的情况。

src/styles/markdown.css
/* 引入 expressiveCode，注释以下代码
pre {
    @apply bg-[var(--codeblock-bg)] !important;
    @apply rounded-xl px-5;


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


        ::selection {
            @apply bg-[var(--codeblock-selection)];
        }
    }
}
*/
.expressive-code {
    @apply mb-6;
}

集成 Expressive Code 基本#

首先需要安装Expressive Code，使用你的nodejs包管理器安装即可，例如：

Terminal window
pnpm astro add astro-expressive-code

修改 astro 配置文件添加 Expressive Code 集成，你可以参考文档进行一些配置。其中关键的主题切换功能实现在themeCssSelector的配置。这是官方提供的一种自定义主题切换机制，该配置项接受一个函数，并根据该函数的计算结果，生成对应的CSS代码。请放心，接收的是一个函数，但这个功能是静态的，只会影响构建后的CSS选择器。

此外，为避免影响CSS的生成，建议禁用掉useDarkModeMediaQuery功能。禁用掉这个功能并不会影响并不会影响prefers-color-scheme的作用，因为Fuwari已经为我们适配了prefers-color-scheme。

astro.config.mjs
...
import expressiveCode from "astro-expressive-code";
...
export default defineConfig({
  site: "https://kasuha.com",
  base: "/",
  trailingSlash: "always",
  integrations: [
    ...
    expressiveCode({
      themes: ["one-light", "min-dark"],
      useDarkModeMediaQuery: false,
      themeCssSelector: (theme) => (theme.type === "dark" ? ".dark" : ""),
      emitExternalStylesheet: true,
    }),
  ],
  ...
});

注意到上方的代码中，我对Expressive Code主题的设置使用了硬编码的方式，这主要是出于以下考量：

  • 代码块的样式也是主题的一部分，应该由主题作者来定义，通常不需要用户关心。
  • 便于后续根据根据文档对Expressive Code样式进行深度定制，如果开放用户配置主题，将会导致样式不协调。

可选功能#

NOTE

Expressive Code官方提供一些增强插件，如果你不需要这些功能可以跳过。

代码行号#

首先需要安装代码行号插件，然后修改astro.config.mjs中expressiveCode的配置即可，你可以根据官方文档进行客制化配置。

Terminal window
pnpm add @expressive-code/plugin-line-numbers
expressiveCode({
    themes: ["one-light", "min-dark"],
    useDarkModeMediaQuery: false,
    themeCssSelector: (theme) => (theme.type === "dark" ? ".dark" : ""),
    emitExternalStylesheet: true,
    plugins: [pluginLineNumbers()],
}),

代码折叠#

首先需要安装代码折叠插件，然后修改astro.config.mjs中expressiveCode的配置即可，你可以根据官方文档进行客制化配置。

Terminal window
pnpm add @expressive-code/plugin-line-numbers
expressiveCode({
    themes: ["one-light", "min-dark"],
    useDarkModeMediaQuery: false,
    themeCssSelector: (theme) => (theme.type === "dark" ? ".dark" : ""),
    emitExternalStylesheet: true,
    plugins: [pluginCollapsibleSections()],
}),

后续工作#

  1. 可尝试引入代码组功能，参考 Rehype Code Group Plugin

参考资料#

Fuwari 集成 Expressive Code 代码块 ~ 一种低侵略性、少量改动方法
https://kasuha.com/posts/fuwari-expressive-code/
作者
霞葉
发布于
2025-05-20
许可协议
CC BY-NC-SA 4.0
绿联 NAS - DXP4800 开箱与初体验
Fuwari 接入 Waline 评论系统 ~ 可选是否开启评论
评论加载中...
© 2025 霞葉. All Rights Reserved. / RSS / Sitemap
Privacy / Terms of Service / Copyright
Powered by Astro & Fuwari