语法高亮

Astro 内置了对 Shiki 和 Prism 的支持。这为以下内容提供了语法高亮：

• 在 Markdown 或 MDX 文件中使用的所有代码围栏 (```)。
• .astro 文件中内置 <Code /> 组件（由 Shiki驱动）内的内容。
• .astro 文件中<Prism /> 组件（由 Prism 驱动）内的内容。

添加社区集成，如 Expressive Code，可以在你的代码块中获得更多的文本标记和注释选项。

Markdown 代码块

Markdown 代码块由开头和结尾的三个反引号 ``` 表示。你可以在开头的反引号后指定所使用的编程语言，以指明如何为你的代码着色和设置样式，使其更易于阅读。

```js
// Javascript code with syntax highlighting.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};
```

Astro 的 Markdown 代码块默认由 Shiki 进行样式化，并预配置了 github-dark 主题。编译后的输出将仅限于内联 style，不包含任何额外的 CSS 类、样式表或客户端 JS。

你可以使用 markdown.syntaxHighlight 配置选项来添加 Prism 样式表并切换到 Prism 的高亮，或者完全禁用 Astro 的语法高亮。

有关使用 Shiki 时可用的 Markdown 语法高亮选项的完整集合，请参阅完整的 markdown.shikiConfig 参考。

设置默认 Shiki 主题

你可以在 Astro 配置中为你的 Markdown 代码块配置任何内置的 Shiki 主题

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'dracula',
    },
  },
});

有关 Markdown 代码块选项的完整集合，请参阅完整的 Shiki 配置参考。

设置浅色和深色模式主题

你可以在 Astro 配置中为浅色和深色模式指定双重 Shiki 主题

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
    },
  },
});

然后，通过媒体查询或类添加 Shiki 的暗色模式 CSS 变量，以默认应用于所有 Markdown 代码块。将 Shiki 文档示例中的 .shiki 类替换为 .astro-code

src/styles/global.css

@media (prefers-color-scheme: dark) {
  .shiki,
  .shiki span {
  .astro-code,
  .astro-code span {
    color: var(--shiki-dark) !important;
    background-color: var(--shiki-dark-bg) !important;
    /* Optional, if you also want font styles */
    font-style: var(--shiki-dark-font-style) !important;
    font-weight: var(--shiki-dark-font-weight) !important;
    text-decoration: var(--shiki-dark-text-decoration) !important;
  }
}

有关 Markdown 代码块选项的完整集合，请参阅完整的 Shiki 配置参考。

添加你自己的 Shiki 主题

除了使用 Shiki 的预定义主题外，你还可以从本地文件导入自定义的 Shiki 主题。

astro.config.mjs

import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: customTheme,
    },
  },
});

自定义 Shiki 主题

你可以参考 Shiki 自己的主题文档，了解更多关于主题、浅色与深色模式切换或通过 CSS 变量进行样式化的自定义选项。

你需要根据以下替换项调整 Shiki 文档中的示例以适应你的 Astro 项目

• 代码块使用 .astro-code 类进行样式化，而不是 .shiki
• 使用 css-variables 主题时，自定义属性的前缀是 --astro-code- 而不是 --shiki-

用于代码块的组件

有两个 Astro 组件可用于在 .astro 和 .mdx 文件中渲染代码块：<Code /> 和 <Prism />。

你可以使用 ComponentProps 类型工具来引用这些组件的 Props。

<Code />

该组件由 Shiki 内部驱动。它支持所有流行的 Shiki 主题和语言，以及其他一些 Shiki 选项，如自定义主题、语言、转换器和默认颜色。

这些值通过 theme、lang、transformers 和 defaultColor 属性分别作为 props 传递给 <Code /> 组件。 <Code /> 组件不会继承你为 Markdown 代码块设置的 shikiConfig。

---
import { Code } from 'astro:components';
---
<!-- Syntax highlight some JavaScript code. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- Optional: Customize your theme. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- Optional: Enable word wrapping. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- Optional: Output inline code. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
</p>
<!-- Optional: defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

转换器

添加于： astro@4.11.0

可以通过 transformers 属性以数组的形式传递Shiki 转换器来选择性地应用于代码。自 Astro v4.14.0 起，你还可以为 Shiki 的 meta 属性提供一个字符串，以向转换器传递选项。

请注意，transformers 仅应用类，你必须提供自己的 CSS 规则来定位代码块的元素。

src/pages/index.astro

---
import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'
import { Code } from 'astro:components'
const code = `const foo = 'hello'
const bar = ' world'
console.log(foo + bar) // [!code focus]
`
---
<Code
  code={code}
  lang="js"
  transformers={[transformerMetaHighlight()]}
  meta="{1,3}"
/>

<style is:global>
  pre.has-focused .line:not(.focused) {
    filter: blur(1px);
  }
</style>

<Prism />

此组件通过应用 Prism 的 CSS 类为代码块提供特定于语言的语法高亮。请注意，你必须提供 Prism CSS 样式表（或使用你自己的）来为这些类设置样式。

要使用 Prism 高亮组件，你必须安装 @astrojs/prism 包

npm

npm install @astrojs/prism

pnpm

pnpm add @astrojs/prism

Yarn

yarn add @astrojs/prism

然后，你可以像任何其他 Astro 组件一样导入和使用 <Prism /> 组件，传递要渲染的语言和代码。

---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

除了 Prism 支持的语言列表外，你还可以使用 lang="astro" 来显示 Astro 代码块。

添加 Prism 样式表

如果你选择使用 Prism（通过配置 markdown.syntaxHighlight: 'prism' 或使用 <Prism /> 组件），Astro 将会把 Prism 的 CSS 类应用到你的代码上，而不是 Shiki 的。你需要提供你自己的 CSS 样式表才能让语法高亮显示出来。

1. 从可用的 Prism 主题中选择一个预制的样式表。

2. 将此样式表添加到你项目的 public/ 目录中。

3. 在布局组件中，通过 <link> 标签将其加载到页面的 <head> 中。（请参阅 Prism 基本用法。）

你也可以访问 Prism 支持的语言列表以获取选项和用法。