Skip to content

语法高亮

Astro 内置对 志木 和 Prisma 的支持。这提供了语法高亮：

¥Astro comes with built-in support for Shiki and Prism. This provides syntax highlighting for:

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

¥Add community integrations such as Expressive Code for even more text marking and annotation options in your code blocks.

Markdown 代码块

标题部分 Markdown 代码块

¥Markdown code blocks

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

¥A Markdown code block is indicated by a block with three backticks ``` at the start and end. You can indicate the programming language being used after the opening backticks to indicate how to color and style your code to make it easier to read.

// 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。

¥Astro’s Markdown code blocks are styled by Shiki by default, preconfigured with the github-dark theme. The compiled output will be limited to inline styles without any extraneous CSS classes, stylesheets, or client-side JS.

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

¥You can add a Prism stylesheet and switch to Prism’s highlighting, or disable Astro’s syntax highlighting entirely, with the markdown.syntaxHighlight configuration option.

See the full markdown.shikiConfig reference for the complete set of Markdown syntax highlighting options available when using Shiki.

设置默认 Shiki 主题

标题部分 设置默认 Shiki 主题

¥Setting a default Shiki theme

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

¥You can configure any built-in Shiki theme for your Markdown code blocks in your Astro config:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'dracula',
    },
  },
});
See the full Shiki config reference for the complete set of Markdown code block options.

设置明夜间模式主题

标题部分 设置明夜间模式主题

¥Setting light and dark mode themes

你可以在 Astro 配置中为明夜间模式指定双 Shiki 主题：

¥You can specify dual Shiki themes for light and dark mode in your Astro config:

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：

¥Then, add Shiki’s dark mode CSS variables via media query or classes to apply to all your Markdown code blocks by default. Replace the .shiki class in the examples from Shiki’s documentation with .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;
  }
}
See the full Shiki config reference for the complete set of Markdown code block options.

添加你自己的 Shiki 主题

标题部分 添加你自己的 Shiki 主题

¥Adding your own Shiki theme

你可以从本地文件导入自定义 Shiki 主题，而不是使用 Shiki 的预定义主题之一。

¥Instead of using one of Shiki’s predefined themes, you can import a custom Shiki theme from a local file.

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


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

自定义 Shiki 主题

标题部分 自定义 Shiki 主题

¥Customizing Shiki themes

你可以关注 Shiki 自己的主题文档 以获取更多主题自定义选项、亮夜间模式切换或通过 CSS 变量进行样式设置。

¥You can follow Shiki’s own theme documentation for more customization options for themes, light vs dark mode toggles, or styling via CSS variables.

Astro 代码块使用 .astro-code 类进行样式设置，因此你需要将示例中的 .shiki 类替换为 .astro-code。

¥Astro code blocks are styled using the .astro-code class, so you will need to replace the .shiki class in the examples with .astro-code.

代码块的组件

标题部分 代码块的组件

¥Components for code blocks

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

¥There are two Astro components available for .astro and .mdx files to render code blocks: <Code /> and <Prism />.

你可以使用 ComponentProps 型 实用程序引用这些组件的 Props。

¥You can reference the Props of these components using the ComponentProps type utility.

<Code />

标题部分 &lt;Code /&gt;

此组件由 Shiki 内部提供支持。它支持所有流行的 Shiki 主题和语言以及其他几个 Shiki 选项，如自定义主题、语言、transformers 和默认颜色。

¥This component is powered internally by Shiki. It supports all popular Shiki themes and languages as well as several other Shiki options such as custom themes, languages, transformers, and default colors.

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

¥These values are passed to the <Code /> component using the theme, lang, transformers, and defaultColor attributes respectively as props. The <Code /> component will not inherit your shikiConfig settings for Markdown code blocks.

---
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} />

Transformers

标题部分 Transformers

Added in: astro@4.11.0

可以选择将 Shiki 变换器 应用于代码，方法是将它们作为数组通过 transformers 属性传入。自 Astro v4.14.0 起，你还可以为 Shiki 的 meta 属性 提供一个字符串，以将选项传递给转换器。

¥Shiki transformers can optionally be applied to code by passing them in through the transformers property as an array. Since Astro v4.14.0, you can also provide a string for Shiki’s meta attribute to pass options to transformers.

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

¥Note that transformers only applies classes and you must provide your own CSS rules to target the elements of your code block.

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 />

标题部分 &lt;Prism /&gt;

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

¥This component provides language-specific syntax highlighting for code blocks by applying Prism’s CSS classes. Note that you must provide a Prism CSS stylesheet (or bring your own) to style the classes.

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

¥To use the Prism highlighter component, you must install the @astrojs/prism package:

终端窗口
npm install @astrojs/prism

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

¥Then, you can import and use the <Prism /> component like any other Astro component, passing a language and the code to render.

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

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

¥In addition to the list of languages supported by Prism, you can also use lang="astro" to display Astro code blocks.

添加 Prism 样式表

标题部分 添加 Prism 样式表

¥Add a Prism stylesheet

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

¥If you opt to use Prism (either by configuring markdown.syntaxHighlight: 'prism' or with the <Prism /> component), Astro will apply Prism’s CSS classes instead of Shiki’s to your code. You will need to bring your own CSS stylesheet for syntax highlighting to appear.

  1. Choose a premade stylesheet from the available Prism Themes.

  2. Add this stylesheet to your project’s public/ directory.

  3. Load this into your page’s <head> in a layout component via a <link> tag. (See Prism basic usage.)

你还可以访问 Prism 支持的语言列表 了解选项和用法。

¥You can also visit the list of languages supported by Prism for options and usage.

Astro 中文网 - 粤ICP备13048890号