Astro Expressive Code 主題與深色模式設定

用Astro Expressive Code套件在程式碼區塊製作可複製按鈕與深色模式

可複製按鈕

方法一、使用現成的外部套件

如果使用的是 Astro 預設的 Markdown / MDX 處理器（使用 Expressive Code 或 Shiki），可以直接安裝社群開發好的外掛，省去自己寫 JavaScript 的時間。

其中 astro-expressive-code 是目前 Astro 官方強烈推薦且內建整合度最高的組件，它預設就自帶複製按鈕，而且樣式非常美觀。

步驟：

安裝套件：

npm i astro-expressive-code

在 astro.config.mjs 中加入設定：

import { defineConfig } from 'astro/config';
import expressiveCode from 'astro-expressive-code';
import mdx from '@astrojs/mdx'; // 如果你有用 MDX

export default defineConfig({
  integrations: [
    expressiveCode(), // 注意：必須放在 mdx() 或 sitemap() 之前
    mdx(),
  ],
});

完成！現在滑鼠移過去時，右上角就會自動出現複製按鈕。

方法二：純原生 JavaScript 實作（自由度最高）

總結建議

想省時間、要功能強大（如：顯示檔名、行號高亮）：選方法一 (Expressive Code)。
想完全自訂樣式、不想增加打包體積：選方法二（原生JS）。

深色模式

astro-expressive-code 內建支援同時顯示單一主題或依據系統自動切換雙主題（深色/淺色）。

可以直接在 astro.config.mjs 中進行設定。

以下是常見的兩種調整方式：

方案 A：強制全面使用「深色模式」

如果希望不論使用者的系統是深色還是淺色，程式碼區塊一律都顯示深色，可以直接在 themes 陣列只填入一個深色主題（例如內建的 github-dark 或 dracula）： JavaScript

import { defineConfig } from 'astro/config';
import expressiveCode from 'astro-expressive-code';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    expressiveCode({
      // 只指定一個深色主題
      themes: ['github-dark'],
    }),
    mdx(),
  ],
});

方案 B：自動跟隨網頁切換（深色/淺色雙主題）

如果網站本身有深淺色切換功能，希望程式碼區塊也能跟著變，你可以傳入兩個主題。astro-expressive-code 會自動根據網頁的 CSS（例如 prefers-color-scheme 或 HTML 上的 .dark 類別）來切換。 JavaScript

import { defineConfig } from 'astro/config';
import expressiveCode from 'astro-expressive-code';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    expressiveCode({
      // 第一個是預設（淺色），第二個是深色
      themes: ['github-light', 'github-dark'],

      // 如果你的網站是用 <html class="dark"> 來控制深色模式，可以加上這行設定：
      useDarkModeMediaQuery: false,
    }),
    mdx(),
  ],
});

小提示：

如果你使用了雙主題，且網站是用 class=“dark” 切換，預設情況下它會產出兩套 CSS。當外層有 .dark 類別時，就會自動切換成第二個深色主題，完全不需要寫額外的 JavaScript。

內建熱門主題推薦

直接在 themes 陣列中填寫以下任何一個內建的主題名稱，不需要額外安裝：

github-dark (經典深色)
dracula (吸血鬼風格深色)
nord (北歐極地深色)
solarized-dark (暖調深色)
one-dark-pro (熱門的 VS Code 暗色主題)