博客使用 - 中级篇

2025年5月16日

cmssky

组件

使用组件

组件能让你更轻松、更连贯地复用部分 UI 或者样式。示例可能包括链接卡片或嵌入 YouTube。 Starlight 支持使用 MDX 和 Markdoc 文件中的组件，并提供了一些常用组件供你使用。

在 Astro 文档中了解有关构建组件的更多信息。

在 MDX 中使用组件

你可以通过将组件导入 MDX 文件然后将其渲染为 JSX 标签来使用该组件。这些组件看起来像 HTML 标签，但是以 import 语句中的大写字母开头，并与之名称相匹配：

1
---
2
title: 欢迎来到我的文档
3
---
4

5
import { Icon } from '@astrojs/starlight/components';
6
import CustomCard from '../../components/CustomCard.astro';
7

8
<Icon name="open-book" />
9

10
<CustomCard>组件还可以包含 **嵌套内容**。</CustomCard>

由于 Starlight 由 Astro 提供支持，因此你可以在 MDX 文件中添加由受支持的 UI 框架（React、Preact、Svelte、Vue、Solid 和 Alpine）构建的组件。在 Astro 文档中了解有关在 MDX 中使用组件的更多信息。

在 Markdoc 中使用组件

跟随我们的 Markdoc 设置指南来添加支持以在 Markdoc 中创作内容。

使用 Starlight 的 Markdoc 预设，你可以将 Starlight 的内置组件与 Markdoc 的 {% %} 标签语法结合使用。与 MDX 不同的是，Markdoc 中的组件不需要导入。以下示例为，在 Markdoc 文件中渲染 Starlight 的卡片组件：

1
---
2
title: 欢迎来到我的文档
3
---
4

5
{% card title="星星" icon="star" %}
6
天狼星, 织女星, 参宿四
7
{% /card %}

有关如何使用 Markdoc 文件中的组件的更多信息，请参阅 Astro Markdoc 集成文档。

内置组件

Starlight 为常见文档用例提供内置组件。这些组件可从 MDX 文件中的 @astrojs/starlight/components 包以及 Markdoc 文件中的 Starlight Markdoc 预设中获取。

请参阅侧边栏以获取可用组件的列表以及使用方式。

和 Starlight 样式的兼容性

Starlight 将默认样式应用于 Markdown 内容，例如，在元素之间添加边距。如果这些样式与你的组件外观存在冲突，请在组件上设置 not-content 类来禁用它们。

1
<div class="not-content">
2
  <p>不受 Starlight 默认内容样式的影响。</p>
3
</div>

组件 props

使用 astro/types 中的 ComponentProps 类型来引用组件接受的 Props，即使它们不是由组件本身导出的。这在包装或扩展现有组件时非常有用。

以下示例为，使用 ComponentProps 获取 Starlight 内置 Badge 组件接受的 props 类型：

1
---
2
import type { ComponentProps } from 'astro/types';
3
import { Badge } from '@astrojs/starlight/components';
4

5
type BadgeProps = ComponentProps<typeof Badge>;
6
---

图标

显示图标

要显示 Starlight 内置图标集中的图标，请使用 <Icon> 组件。

图标导入

1
import { Icon } from '@astrojs/starlight/components';

图标用法

使用 <Icon> 组件来显示图标。图标需要将 name 设置为 Starlight 的内置图标之一，并且可以选择是否包含 label 来为屏幕阅读器提供上下文。

MDX
Markdoc

1
import { Icon } from '@astrojs/starlight/components';
2

3
<Icon name="star" />
4
<Icon name="starlight" label="Starlight 的 logo" />

1
{% icon name="star" /%}
2
{% icon name="starlight" label="Starlight 的 logo" /%}

预览

自定义图标

size 和 color 属性可使用 CSS 单位和颜色值来调整图标的外观。 class 属性可用于向图标添加自定义 CSS 类。

MDX
Markdoc

1
import { Icon } from '@astrojs/starlight/components';
2

3
<Icon name="star" color="goldenrod" size="2rem" />
4
<Icon name="rocket" color="var(--sl-color-text-accent)" />

1
{% icon name="star" color="goldenrod" size="2rem" /%}
2
{% icon name="rocket" color="var(--sl-color-text-accent)" /%}

预览

`<Icon>` 的属性

实现： Icon.astro

<Icon> 组件接受以下属性：

`name`

必要属性类型： StarlightIcon

要显示的图标名称设置为 Starlight 的内置图标之一。

`label`

类型： string

一个可选标签，用于为无障碍技术（例如屏幕阅读器）提供上下文。

当未设置 label 时，该图标将在无障碍下完全隐藏。在这种情况下，请确保在没有图标的情况下，上下文仍然可以理解。例如，仅具有图标的链接必须包含 label 属性才能易于识读，但如果链接已经包含了文本，并且图标纯粹是装饰性的，那么省略 label 也许更有意义。

`size`

类型： string

图标的大小使用 CSS 单位。

`color`

类型： string

使用 CSS 颜色值的图标颜色。

`class`

类型： string

要添加到图标的自定义 CSS 类。

所有图标

下面显示了所有可用图标，包括它们对应名称的列表。单击图标将其名称复制到剪贴板。

旁白

显示旁白

要在页面的主要内容旁边显示次要信息，请使用 <Aside> 组件。

旁白导入

1
import { Aside } from '@astrojs/starlight/components';

旁白用法

使用 <Aside> 组件以显示旁白（也称为“警告”或“标注”）。

<Aside> 有一个可选的 type 属性，它控制着旁白的颜色、图标和默认标题。

MDX
Markdoc

1
import { Aside } from '@astrojs/starlight/components';
2

3
<Aside>一些在旁白中的内容。</Aside>
4

5
<Aside type="caution">一些警示内容。</Aside>
6

7
<Aside type="tip">
8

9
旁白中还支持其他内容。
10

11
```js
12
// 例如，代码片段。
13
```
14

15
</Aside>
16

17
<Aside type="danger">不要将你的密码告诉任何人。</Aside>

1
{% aside %}
2
一些在旁白中的内容。
3
{% /aside %}
4

5
{% aside type="caution" %}
6
一些警示内容。
7
{% /aside %}
8

9
{% aside type="tip" %}
10
旁白中还支持其他内容。
11

12
```js
13
// 例如，代码片段。
14
```
15
{% /aside %}
16

17
{% aside type="danger" %}
18
不要将你的密码告诉任何人。
19
{% /aside %}

预览

Starlight 还提供了用于在 Markdown 和 MDX 中渲染旁白的自定义语法，以此作为 <Aside> 组件的替代方案。有关自定义语法的详细信息，请参阅 “在 Markdown 中创作内容” 指南。

使用自定义标题

使用 title 属性覆盖默认的旁白标题。

MDX
Markdoc

1
import { Aside } from '@astrojs/starlight/components';
2

3
<Aside type="caution" title="当心！">
4
  *带有* 自定义标题的警告。
5
</Aside>

1
{% aside type="caution" title="当心！" %}
2
*带有* 自定义标题的警告。
3
{% /aside %}

预览

`<Aside>` 的属性

实现： Aside.astro

<Aside> 组件接受以下属性：

`type`

类型： 'note' | 'tip' | 'caution' | 'danger'
默认值： 'note'

要显示的旁白类型：

note 旁白（默认）为蓝色，并带有一个信息的图标。
tip 旁白为紫色，并带有一个火箭的图标。
caution 旁白为黄色，并带有一个三角警示图标。
danger 旁白为红色。并带有一个八边形警示图标。

`title`

类型： string

要显示的旁白的标题。如果未设置 title，则将使用当前旁白的 type 作为默认标题。

文件树

显示文件树

要显示带有文件图标和可折叠子目录的目录结构，请使用 <FileTree> 组件。

1
<FileTree>
2

3
- astro.config.mjs 一个 **重要** 文件
4
- package.json
5
- README.md
6
- src
7
  - components
8
    - **Header.astro**
9
  - …
10
- pages/
11

12
</FileTree>

预览

astro.config.mjs 一个重要文件
package.json
README.md
文件夹src
- 文件夹components
  - Header.astro
- …
文件夹pages/
- …

文件树导入

1
import { FileTree } from '@astrojs/starlight/components';

文件树用法

使用 <FileTree> 组件可以显示带有文件图标和可折叠子目录的文件树。

使用 <FileTree> 内的无序 Markdown 列表来指定文件和目录的结构。使用嵌套列表可以创建子目录，或在列表项末尾添加 / 以将其渲染为没有特定内容的目录。

MDX
Markdoc

1
import { FileTree } from '@astrojs/starlight/components';
2

3
<FileTree>
4

5
- astro.config.mjs
6
- package.json
7
- src
8
  - components
9
    - Header.astro
10
    - Title.astro
11
  - pages/
12

13
</FileTree>

1
{% filetree %}
2
- astro.config.mjs
3
- package.json
4
- src
5
  - components
6
    - Header.astro
7
    - Title.astro
8
  - pages/
9
{% /filetree %}

预览

astro.config.mjs
package.json
文件夹src
- 文件夹components
  - Header.astro
  - Title.astro
- 文件夹pages/
  - …

高亮显示条目

通过将文件或目录的名称加粗，来使文件或目录从中脱颖而出，例如 **README.md**。

MDX
Markdoc

1
import { FileTree } from '@astrojs/starlight/components';
2

3
<FileTree>
4

5
- src
6
  - components
7
    - **Header.astro**
8
    - Title.astro
9

10
</FileTree>

1
{% filetree %}
2
- src
3
  - components
4
    - **Header.astro**
5
    - Title.astro
6
{% /filetree %}

预览

文件夹src
- 文件夹components
  - Header.astro
  - Title.astro

添加注释

通过在名称后添加更多文本来向文件或目录添加注释。注释中支持内联 Markdown 格式，例如粗体和斜体。

MDX
Markdoc

1
import { FileTree } from '@astrojs/starlight/components';
2

3
<FileTree>
4

5
- src
6
  - components
7
    - Header.astro 一个 **重要** 文件
8
    - Title.astro
9

10
</FileTree>

1
{% filetree %}
2
- src
3
  - components
4
    - Header.astro 一个 **重要** 文件
5
    - Title.astro
6
{% /filetree %}

预览

文件夹src
- 文件夹components
  - Header.astro 一个重要文件
  - Title.astro

添加占位符

将 ... 或 … 作为名称来添加占位符文件和目录。这可用于向读者指示文件夹应包含更多项目，而无需明确指定所有项目。

MDX
Markdoc

1
import { FileTree } from '@astrojs/starlight/components';
2

3
<FileTree>
4

5
- src
6
  - components
7
    - Header.astro
8
    - …
9

10
</FileTree>

1
{% filetree %}
2
- src
3
  - components
4
    - Header.astro
5
    - …
6
{% /filetree %}

预览

文件夹src
- 文件夹components
  - Header.astro
  - …

`<FileTree>` 的属性

实现： FileTree.astro

<FileTree> 组件不接受任何 props。

步骤

显示步骤

要设置任务编号列表的样式以创建分步指南，请使用 <Steps> 组件。

创建一个新的 Starlight 项目：

1
npm create astro@latest -- --template canjieorg/canjie blog && cd blog && npm install

1
pnpm create astro@latest -- --template canjieorg/canjie blog && cd blog && pnpm install

1
yarn create astro --template canjieorg/canjie blog && cd blog && yarn install

编写你的第一个文档页面。

步骤导入

1
import { Steps } from '@astrojs/starlight/components';

步骤用法

使用 <Steps> 组件来设置任务编号列表的样式。这对于需要清楚地显示出有关每个步骤的、更复杂的分步指南来说，非常有用。

用 <Steps> 将标准的 Markdown 有序列表包裹起来。所有常用的 Markdown 语法都适用于 <Steps>。

MDX
Markdoc

1
import { Steps } from '@astrojs/starlight/components';
2

3
<Steps>
4

5
1. 将组件导入到 MDX 文件中：
6

7
   ```js
8
   import { Steps } from '@astrojs/starlight/components';
9
   ```
10

11
2. 用 `<Steps>` 将你的有序列表包裹起来。
12

13
</Steps>

1
{% steps %}
2

3
1. 将组件导入到 MDX 文件中：
4

5
   ```js
6
   import { Steps } from '@astrojs/starlight/components';
7
   ```
8

9
2. 用 `<Steps>` 将你的有序列表包裹起来。
10

11
{% /steps %}

预览

将组件导入到 MDX 文件中：

1
import { Steps } from '@astrojs/starlight/components';

用 <Steps> 将你的有序列表包裹起来。

`<Steps>` 的属性

实现： Steps.astro

<Steps> 组件不接受任何 props。

卡片

要在框中显示与 Starlight 样式匹配的内容，请使用 <Card> 组件。

卫星

木卫一，木卫二，木卫三

导入卡片

1
import { Card } from '@astrojs/starlight/components';

卡片用法

使用 <Card> 组件来显示卡片，并为其提供一个 title。

MDX
Markdoc

1
import { Card } from '@astrojs/starlight/components';
2

3
<Card title="试试这个">一些你想着重展示的有趣内容。</Card>

1
{% card title="试试这个" %}
2
一些你想着重展示的有趣内容。
3
{% /card %}

预览

试试这个

一些你想着重展示的有趣内容。

为卡片添加图标

要在卡片中包含一个图标，请把 icon 属性设置为 Starlight 的内置图标名称之一。

MDX
Markdoc

1
import { Card } from '@astrojs/starlight/components';
2

3
<Card title="星星" icon="star">
4
  天狼星，织女星，参宿四
5
</Card>

1
{% card title="星星" icon="star" %}
2
天狼星，织女星，参宿四
3
{% /card %}

预览

星星

天狼星，织女星，参宿四

分组卡片

当有足够大的空间时，可以使用 <CardGrid> 组件将多个卡片分组，并排显示多个卡片。有关示例，请参阅 “分组卡片” 指南。

`<Card>` 的属性

实现： Card.astro

<Card> 组件接受以下属性：

`title`

必要属性
类型： string

要显示的卡片标题。

`icon`

类型： string

将 icon 属性设置为 Starlight 的内置图标名称之一，能够使卡片包含一个图标。

链接卡片

要突出显示不同页面的链接，请使用 <LinkCard> 组件。

自定义 Starlight 学习如何通过自定义样式、字体等使你的 Starlight 网站变得与众不同。

卡片导入

1
import { LinkCard } from '@astrojs/starlight/components';

卡片用法

使用 <LinkCard> 组件来突出显示链接。每个 <LinkCard> 都需要一个 title 和一个 href 属性。

MDX
Markdoc

1
import { LinkCard } from '@astrojs/starlight/components';
2

3
<LinkCard title="Markdown 创作" href="/zh-cn/guides/authoring-content/" />

1
{% linkcard title="Markdown 创作" href="/zh-cn/guides/authoring-content/" /%}

预览

Markdown 创作

添加链接描述

使用 description 属性向链接卡片添加一个简短的描述。

MDX
Markdoc

1
import { LinkCard } from '@astrojs/starlight/components';
2

3
<LinkCard
4
  title="国际化"
5
  href="/zh-cn/guides/i18n/"
6
  description="配置 Starlight 以支持多种语言。"
7
/>

1
{% linkcard
2
   title="国际化"
3
   href="/zh-cn/guides/i18n/"
4
   description="配置 Starlight 以支持多种语言。" /%}

预览

国际化配置 Starlight 以支持多种语言。

分组链接卡片

当有足够大的空间时，可以使用 <CardGrid> 组件对链接卡片进行分组，来并排显示多个链接卡片。有关示例，请参阅 “分组链接卡片” 指南。

`<LinkCard>` 的属性

实现： LinkCard.astro

<LinkCard> 组件接受以下属性，以及其他所有的 <a> 元素属性：

`title`

必要属性
类型： string

要显示的链接卡片的标题。

`href`

必要属性
类型： string

与卡片交互时所链接到的 URL。

`description`

类型： string

一个可选描述，显示在标题的下方。

卡片网格

要将多个 <Card> 或 <LinkCard> 组件包装在网格中，请使用 <CardGrid> 组件。

星星

天狼星，织女星，参宿四

卫星

木卫一，木卫二，木卫三

卡片导入

1
import { CardGrid } from '@astrojs/starlight/components';

卡片用法

分组卡片

当有足够大的空间时，可以使用 <CardGrid> 组件对卡片进行分组，并排显示多个 <Card> 组件。

MDX
Markdoc

1
import { Card, CardGrid } from '@astrojs/starlight/components';
2

3
<CardGrid>
4
  <Card title="试试这个" icon="open-book">
5
    一些你想着重展示的有趣内容。
6
  </Card>
7
  <Card title="其他功能" icon="information">
8
    更多你想分享的信息。
9
  </Card>
10
</CardGrid>

1
{% cardgrid %}
2
{% card title="试试这个" icon="open-book" %}
3
一些你想着重展示的有趣内容。
4
{% /card %}
5

6
{% card title="其他功能" icon="information" %}
7
更多你想分享的信息。
8
{% /card %}
9
{% /cardgrid %}

预览

试试这个

一些你想着重展示的有趣内容。

其他功能

更多你想分享的信息。

分组链接卡片

当有足够大的空间时，可以使用 <CardGrid> 组件对链接卡片进行分组，并排显示多个 <LinkCard> 组件。

MDX
Markdoc

1
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
2

3
<CardGrid>
4
  <LinkCard title="Markdown 创作" href="/zh-cn/guides/authoring-content/" />
5
  <LinkCard title="组件" href="/zh-cn/components/using-components/" />
6
</CardGrid>

1
{% cardgrid %}
2
{% linkcard title="Markdown 创作" href="/zh-cn/guides/authoring-content/" /%}
3

4
{% linkcard title="组件" href="/zh-cn/components/using-components/" /%}
5
{% /cardgrid %}

预览

Markdown 创作

组件

交错卡片

通过向 <CardGrid> 组件添加 stagger 属性，使网格的第二列卡片向着垂直方向移动，从而增添视觉趣味。

该属性在主页上非常有用，可用于展示项目的核心功能。

MDX
Markdoc

1
import { Card, CardGrid } from '@astrojs/starlight/components';
2

3
<CardGrid stagger>
4
  <Card title="试试这个" icon="open-book">
5
    一些你想着重展示的有趣内容。
6
  </Card>
7
  <Card title="其他功能" icon="information">
8
    更多你想分享的信息。
9
  </Card>
10
</CardGrid>

1
{% cardgrid stagger=true %}
2
{% card title="试试这个" icon="open-book" %}
3
一些你想着重展示的有趣内容。
4
{% /card %}
5

6
{% card title="其他功能" icon="information" %}
7
更多你想分享的信息。
8
{% /card %}
9
{% /cardgrid %}

预览

试试这个

一些你想着重展示的有趣内容。

其他功能

更多你想分享的信息。

`<CardGrid>` 的属性

实现： CardGrid.astro

<CardGrid> 组件接受以下属性：

`stagger`

类型： boolean

定义是否在网格中交错卡片。

徽章

要显示小段信息，例如状态或类别，请使用 <Badge> 组件。

新

徽章导入

1
import { Badge } from '@astrojs/starlight/components';

徽章用法

使用 <Badge> 组件显示徽章，并将要显示的内容传递给 <Badge> 组件的 text 属性。

默认情况下，徽章将使用你网站主题的强调色。要使用徽章内置的某一种颜色，请将 variant 属性设置为支持的值之一。

MDX
Markdoc

1
import { Badge } from '@astrojs/starlight/components';
2

3
- <Badge text="注释" variant="note" />
4
- <Badge text="成功" variant="success" />
5
- <Badge text="提示" variant="tip" />
6
- <Badge text="注意" variant="caution" />
7
- <Badge text="危险" variant="danger" />

1
- {% badge text="注释" variant="note" /%}
2
- {% badge text="成功" variant="success" /%}
3
- {% badge text="提示" variant="tip" /%}
4
- {% badge text="注意" variant="caution" /%}
5
- {% badge text="危险" variant="danger" /%}

预览

注释
成功
提示
注意
危险

使用不同的尺寸

使用 size 属性来控制徽章文本的大小。

MDX
Markdoc

1
import { Badge } from '@astrojs/starlight/components';
2

3
- <Badge text="新" size="small" />
4
- <Badge text="更新更强" size="medium" />
5
- <Badge text="更新更强更逼格" size="large" />

1
- {% badge text="新" size="small" /%}
2
- {% badge text="更新更强" size="medium" /%}
3
- {% badge text="更新更强更逼格" size="large" /%}

预览

新
更新更强
更新更强更逼格

自定义徽章

通过使用任何其他 <span> 属性（例如带有自定义 CSS 的 class 或 style）来自定义徽章。

MDX
Markdoc

1
import { Badge } from '@astrojs/starlight/components';
2

3
<Badge text="自定义" variant="success" style={{ fontStyle: 'italic' }} />

1
{% badge text="自定义" variant="success" style="font-style: italic;" /%}

预览

自定义

`<Badge>` 的属性

实现： Badge.astro

<Badge> 组件接受以下属性，以及所有其他的 <span> 属性：

`text`

必要属性
类型： string

要在徽章中显示的文本内容。

`variant`

要使用的徽章颜色变体：note（蓝色）、tip（紫色）、danger（红色）、caution（橙色）、success（绿色）或 defaul（主题强调色）。

`size`

类型： 'small' | 'medium' | 'large'

定义要显示的徽章的大小。

链接按钮

要在视觉上展示不同的号召性用语链接，请使用 <LinkButton> 组件。

阅读文档

链接按钮导入

1
import { LinkButton } from '@astrojs/starlight/components';

链接按钮用法

使用 <LinkButton> 组件，以在视觉上展示独特的号召性用语链接。链接按钮可用于将用户引导至紧密关联或可操作的部分，并且通常在登陆页面上使用。

<LinkButton> 需要 href 属性。可选部分有，使用 variant 属性来自定义链接按钮的外观，该属性可以设置为 primary（默认值）、secondary 或 minimal。

MDX
Markdoc

1
import { LinkButton } from '@astrojs/starlight/components';
2

3
<LinkButton href="/zh-cn/getting-started/">开始使用</LinkButton>
4
<LinkButton href="/zh-cn/reference/configuration/" variant="secondary">
5
  配置参考
6
</LinkButton>

1
{% linkbutton href="/zh-cn/getting-started/" %}开始使用{% /linkbutton %}
2

3
{% linkbutton href="/zh-cn/reference/configuration/" variant="secondary" %}
4
配置参考
5
{% /linkbutton %}

预览

开始使用

配置参考

向链接按钮添加图标

使用设置为 Starlight 内置图标之一名称的 icon 属性，以在链接按钮中包含图标。

可通过设置 iconPlacement 属性为 start（默认为 end）来将图标放置在文本之前。

MDX
Markdoc

1
import { LinkButton } from '@astrojs/starlight/components';
2

3
<LinkButton
4
  href="https://docs.astro.build"
5
  variant="secondary"
6
  icon="external"
7
  iconPlacement="start"
8
>
9
  有关内容：Astro
10
</LinkButton>

1
{% linkbutton
2
   href="https://docs.astro.build"
3
   variant="secondary"
4
   icon="external"
5
   iconPlacement="start" %}
6
有关内容：Astro
7
{% /linkbutton %}

预览

有关内容：Astro

`<LinkButton>` 的属性

实现： LinkButton.astro

<LinkButton> 组件接受以下属性以及任何其他 <a> 属性：

`href`

必要属性
类型： string

链接按钮指向的 URL。

`variant`

类型： 'primary' | 'secondary' | 'minimal'
默认值： 'primary'

链接按钮的外观。将链接设置为 primary 用于显示主题强调色的号召性用语链接；设置为 secondary 用于显示不太显眼的链接；设置为 minimal 用于显示最低优先级的链接。

`icon`

类型： string

链接按钮可以包含一个 icon 属性，该属性应设置为 Starlight 的内置图标之一的名称。

`iconPlacement`

类型： 'start' | 'end'
默认值： 'end'

决定了图标相对于链接按钮文本的位置。

选项卡

要创建选项卡式界面，请使用 <Tabs> 和 <TabItem> 组件。选项卡对于给等效信息进行分组非常有用，用户只需查看多个选项之一即可。

恒星
卫星

天狼星，织女星，参宿四

选项卡导入

1
import { Tabs, TabItem } from '@astrojs/starlight/components';

选项卡用法

使用 <Tabs> 和 <TabItem> 组件以显示选项卡式的界面。每个 <TabItem> 必须有一个 label 来展示给用户。

MDX
Markdoc

1
import { Tabs, TabItem } from '@astrojs/starlight/components';
2

3
<Tabs>
4
  <TabItem label="恒星">天狼星，织女星，参宿四</TabItem>
5
  <TabItem label="卫星">木卫一，木卫二，木卫三</TabItem>
6
</Tabs>

1
{% tabs %}
2
{% tabitem label="恒星" %}
3
天狼星，织女星，参宿四
4
{% /tabitem %}
5

6
{% tabitem label="卫星" %}
7
木卫一，木卫二，木卫三
8
{% /tabitem %}
9
{% /tabs %}

预览

恒星
卫星

天狼星，织女星，参宿四

同步选项卡

通过添加 syncKey 属性来保持多个选项卡组之间的同步。

页面上具有相同 syncKey 值的所有 <Tabs> 将显示相同的活动标签。这允许你的读者只需选择一次（例如选择他们的操作系统或包管理器），就可以看到他们的选择在页面导航中保持一致。

要同步相关选项卡，请向每个 <Tabs> 组件添加相同的 syncKey 属性，并确保它们都使用相同的 <TabItem> labels 属性：

MDX
Markdoc

1
import { Tabs, TabItem } from '@astrojs/starlight/components';
2

3
_一些恒星：_
4

5
<Tabs syncKey="星座">
6
  <TabItem label="猎户座">参宿五，参宿七，参宿四</TabItem>
7
  <TabItem label="双子座">北河三，北河二 A，北河二 B</TabItem>
8
</Tabs>
9

10
_一些系外行星：_
11

12
<Tabs syncKey="星座">
13
  <TabItem label="猎户座">HD 34445 b，格利泽 179b，Wasp-82 b</TabItem>
14
  <TabItem label="双子座">北河三 b，HAT-P-24b，HD 50554 b</TabItem>
15
</Tabs>

1
_一些恒星：_
2

3
{% tabs syncKey="星座" %}
4
{% tabitem label="猎户座" %}
5
参宿五，参宿七，参宿四
6
{% /tabitem %}
7

8
{% tabitem label="双子座" %}
9
北河三，北河二 A，北河二 B
10
{% /tabitem %}
11
{% /tabs %}
12

13
_一些系外行星：_
14

15
{% tabs syncKey="星座" %}
16
{% tabitem label="猎户座" %}
17
HD 34445 b，格利泽 179b，Wasp-82 b
18
{% /tabitem %}
19

20
{% tabitem label="双子座" %}
21
北河三 b，HAT-P-24b，HD 50554 b
22
{% /tabitem %}
23
{% /tabs %}

预览

一些恒星：

猎户座
双子座

参宿五，参宿七，参宿四

一些系外行星：

猎户座
双子座

HD 34445 b，格利泽 179b，Wasp-82 b

为选项卡添加图标

在选项卡组件中，添加 icon 属性并将其设置为 Starlight 内置图标之一来为选项卡添加图标。

MDX
Markdoc

1
import { Tabs, TabItem } from '@astrojs/starlight/components';
2

3
<Tabs>
4
  <TabItem label="恒星" icon="star">
5
    天狼星，织女星，参宿四
6
  </TabItem>
7
  <TabItem label="卫星" icon="moon">
8
    木卫一，木卫二，木卫三
9
  </TabItem>
10
</Tabs>

1
{% tabs %}
2
{% tabitem label="恒星" icon="star" %}
3
天狼星，织女星，参宿四
4
{% /tabitem %}
5

6
{% tabitem label="卫星" icon="moon" %}
7
木卫一，木卫二，木卫三
8
{% /tabitem %}
9
{% /tabs %}

预览

恒星
卫星

天狼星，织女星，参宿四

`<Tabs>` 的属性

实现： Tabs.astro

<Tabs> 组件将多个 <TabItem> 组件组合在一起并接受以下属性：

`syncKey`

类型： string

一个用于使多个选项卡组在多个页面之间保持同步的键。

`<TabItem>` 的属性

实现： TabItem.astro

一组选项卡（tabs）由选项卡项（tab items）组成，每个选项卡项都具有以下属性：

`label`

必要属性
类型： string

选项卡项必须包含一个 label 属性，该属性决定了将在选项卡项中显示的文本。

`icon`

类型： string

每个选项卡项都可以包含一个 icon 属性，该属性设置为 Starlight 的内置图标之一的名称，以在标签旁边显示图标。

代码

无需导入组件，即可渲染代码

在 markdown / MDX 中的使用

常规语法高亮

要使代码块语法高亮显示，请将它们包裹在代码栅栏中（使用三个或更多反引号），并确保打开的代码栅栏包含语言标识符，例如 js JavaScript：

1
```js
2
console.log('This code is syntax highlighted!')
3
```

预览

1
console.log('This code is syntax highlighted!')

渲染 ANSI 转义序列 Expressive Code 支持渲染ANSI 转义序列的子集。这对于在文档中显示格式化的终端输出非常有用。

要为代码块启用此功能，请在打开的代码栅栏中将其语言标识符设置为ansi。然后，您可以使用以下 ANSI 转义序列：

1
```ansi
2
[1;4mStandard ANSI colors:[0m
3
- Dimmed:     [2;30m Black [2;31m Red [2;32m Green [2;33m Yellow [2;34m Blue [2;35m Magenta [2;36m Cyan [2;37m White [0m
4
- Foreground: [30m Black [31m Red [32m Green [33m Yellow [34m Blue [35m Magenta [36m Cyan [37m White [0m
5
- Background: [40m Black [41m Red [42m Green [43m Yellow [44m Blue [45m Magenta [46m Cyan [47m White [0m
6
- Reversed:   [7;30m Black [7;31m Red [7;32m Green [7;33m Yellow [7;34m Blue [7;35m Magenta [7;36m Cyan [7;37m White [0m
7

8
[1;4m8-bit colors (showing colors 160-171 as an example):[0m
9
- Dimmed:     [2;38;5;160m 160 [2;38;5;161m 161 [2;38;5;162m 162 [2;38;5;163m 163 [2;38;5;164m 164 [2;38;5;165m 165 [2;38;5;166m 166 [2;38;5;167m 167 [2;38;5;168m 168 [2;38;5;169m 169 [2;38;5;170m 170 [2;38;5;171m 171 [0m
10
- Foreground: [38;5;160m 160 [38;5;161m 161 [38;5;162m 162 [38;5;163m 163 [38;5;164m 164 [38;5;165m 165 [38;5;166m 166 [38;5;167m 167 [38;5;168m 168 [38;5;169m 169 [38;5;170m 170 [38;5;171m 171 [0m
11
- Background: [48;5;160m 160 [48;5;161m 161 [48;5;162m 162 [48;5;163m 163 [48;5;164m 164 [48;5;165m 165 [48;5;166m 166 [48;5;167m 167 [48;5;168m 168 [48;5;169m 169 [48;5;170m 170 [48;5;171m 171 [0m
12
- Reversed:   [7;38;5;160m 160 [7;38;5;161m 161 [7;38;5;162m 162 [7;38;5;163m 163 [7;38;5;164m 164 [7;38;5;165m 165 [7;38;5;166m 166 [7;38;5;167m 167 [7;38;5;168m 168 [7;38;5;169m 169 [7;38;5;170m 170 [7;38;5;171m 171 [0m
13

14
[1;4m24-bit colors (full RGB):[0m
15
- Dimmed:     [2;38;2;34;139;34m ForestGreen - RGB(34,139,34) [2;38;2;102;51;153m RebeccaPurple - RGB(102,51,153) [0m
16
- Foreground: [38;2;34;139;34m ForestGreen - RGB(34,139,34) [38;2;102;51;153m RebeccaPurple - RGB(102,51,153) [0m
17
- Background: [48;2;34;139;34m ForestGreen - RGB(34,139,34) [48;2;102;51;153m RebeccaPurple - RGB(102,51,153) [0m
18
- Reversed:   [7;38;2;34;139;34m ForestGreen - RGB(34,139,34) [7;38;2;102;51;153m RebeccaPurple - RGB(102,51,153) [0m
19

20
[1;4mFont styles:[0m
21
- Default
22
- [1mBold[0m
23
- [2mDimmed[0m
24
- [3mItalic[0m
25
- [4mUnderline[0m
26
- [7mReversed[0m
27
- [9mStrikethrough[0m
28
```

显示

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

支持的语言

开箱即用，支持超过 100 种语言，包括 JavaScript、TypeScript、HTML、CSS、Astro、Markdown、MDX、JSON、YAML 等等。您可以在 GitHub 上找到所有语言标识符的列表。

与 Shiki 的 HTML 输出的区别

如果您将现有站点迁移到使用自定义 CSS 修改语法高亮代码的 Expressive Code，请注意 Expressive Code 生成的 HTML 输出和类与 Shiki 生成的默认输出不匹配。

相反，Shiki 生成的语法标记会转换为 Expressive Code 自己的注释（InlineStyleAnnotation），它提供了高效的多主题支持，并且可以与其他注释结合使用。

如果您需要在某些 HTML 元素上添加额外的类，请考虑编写自己的插件来根据需要修改输出。

配置

当通过框架集成使用此插件时，您可以通过将选项传递给集成来对其进行配置。

以下是常见场景的配置示例：

1
import { defineConfig } from 'astro/config'
2
import starlight from '@astrojs/starlight'
3
// Add this if you want to load a custom language grammar from a file:
4
// import fs from 'node:fs'
5

6
export default defineConfig({
7
  integrations: [
8
    starlight({
9
      title: 'My Starlight site',
10
      expressiveCode: {
11
        // You can use any of the themes bundled with Shiki by name,
12
        // specify a path to JSON theme file, or pass an instance
13
        // of the `ExpressiveCodeTheme` class here:
14
        themes: ['dracula', 'solarized-light'],
15
        shiki: {
16
          // You can pass additional plugin options here,
17
          // e.g. to load custom language grammars:
18
          langs: [
19
            // import('./some-exported-grammar.mjs'),
20
            // JSON.parse(fs.readFileSync('./some-json-grammar.json', 'utf-8'))
21
          ],
22
        },
23
      },
24
    }),
25
  ],
26
})

可用的插件选项

您可以将以下选项传递给插件：

捆绑语言

Type: BundledShikiLanguage[]
Default: undefined
Availability: Astro and Starlight integrations only

允许从完整的 Shiki 包中定义可用于语法高亮显示的语言 ID 子集。

在服务器端渲染 (SSR) 环境中，将此选项设置为您网站上使用的语言可以将捆绑包大小减少多达 80%。

如果未设置此选项，则完整 Shiki 包中的所有语言均可用。

1
import { defineConfig } from 'astro/config'
2
import starlight from '@astrojs/starlight'
3
import cloudflare from '@astrojs/cloudflare'
4

5
export default defineConfig({
6
  integrations: [
7
    starlight({
8
      title: 'My Starlight site',
9
      expressiveCode: {
10
        shiki: {
11
          // Example: Only include languages 'astro' and 'sass'
12
          // in the bundle, reducing SSR bundle size by 80%
13
          bundledLangs: ['astro', 'sass'],
14
        },
15
      },
16
    }),
17
  ],
18
  // Server-side rendering (SSR) must be enabled
19
  // for bundle size trimming to have an effect
20
  output: 'server',
21
  adapter: cloudflare(),
22
})

`引擎`

Type: 'oniguruma' | 'javascript'
Default: 'oniguruma'

Shiki 用于语法高亮的正则表达式引擎。可选项如下：

'oniguruma'：默认引擎，支持所有语法规则，但需要目标环境支持 WebAssembly（WASM）。
'javascript'：纯 JavaScript 引擎，不需要 WASM。Shiki 团队正在持续改进该引擎，目标是实现与 Oniguruma 引擎的完全兼容。如果你的运行环境不支持 WASM，可以使用该引擎。

`语言`

Type: LanguageInput[]
Default: []

用于语法高亮的额外语言列表。

你可以传入任何 Shiki 支持的语言输入类型，例如：

import('./some-exported-grammar.mjs')
JSON.parse(fs.readFileSync('./some-json-grammar.json', 'utf-8'))

更多信息请参阅 Shiki 文档。

语言别名

Type: Record<string, string>
Default:

允许为语言定义别名。键是别名，值是它们所对应的语言 ID。

这些值可以是内置语言，也可以是通过 langs 定义的额外语言。

1
import { defineConfig } from 'astro/config'
2
import starlight from '@astrojs/starlight'
3

4
export default defineConfig({
5
  integrations: [
6
    starlight({
7
      title: 'My Starlight site',
8
      expressiveCode: {
9
        shiki: {
10
          // Allow using the alias 'mjs' for the 'javascript' language
11
          langAlias: {
12
            mjs: 'javascript',
13
          },
14
        },
15
      },
16
    }),
17
  ],
18
})

注入语言到嵌套代码块

Type: boolean
Default: false

默认情况下，langs 中定义的额外语言只在直接包含于其父 Markdown 或 MDX 文档的顶层代码块中可用。

将此选项设置为 true 时，当使用你定义的额外语言的代码块嵌套在外层 markdown、md 或 mdx 代码块内时，也会启用语法高亮。例如：

1
````md
2
This top-level Markdown code block contains a nested `my-custom-lang` code block:
3
```my-custom-lang
4
This nested code block will only be highlighted using `my-custom-lang`
5
if `injectLangsIntoNestedCodeBlocks` is enabled.
6
```
7
````

转换器

Type: ShikiTransformer[]
Default: []

在语法高亮显示期间应该调用的 Shiki 转换器的可选列表。

此选项允许您添加修改 Shiki 生成的标记的转换器以改进语法突出显示，例如通过应用括号匹配或更改某些标记的颜色。

使用其他语法高亮工具

如果你想使用其他语法高亮工具，可以在配置中设置 shiki: false，以防止默认的高亮器被加载。然后你可以为新的语法高亮器编写一个插件，并将其添加到 plugins 数组中。

博客使用 - 中级篇

组件

使用组件

在 MDX 中使用组件

在 Markdoc 中使用组件

内置组件

和 Starlight 样式的兼容性

组件 props

图标

显示图标

图标导入

图标用法

自定义图标

<Icon> 的属性

name

label

size

color

class

所有图标

旁白

显示旁白

旁白导入

旁白用法

使用自定义标题

<Aside> 的属性

type

title

文件树

显示文件树

文件树导入

文件树用法

高亮显示条目

添加注释

添加占位符

<FileTree> 的属性

步骤

显示步骤

步骤导入

步骤用法

<Steps> 的属性

卡片

导入卡片

卡片用法

为卡片添加图标

分组卡片

<Card> 的属性

title

icon

链接卡片

卡片导入

卡片用法

添加链接描述

分组链接卡片

<LinkCard> 的属性

title

href

description

卡片网格

卡片导入

卡片用法

分组卡片

分组链接卡片

交错卡片

<CardGrid> 的属性

stagger

徽章

徽章导入

徽章用法

使用不同的尺寸

自定义徽章

<Badge> 的属性

text

variant

size

链接按钮

链接按钮导入

链接按钮用法

向链接按钮添加图标

<LinkButton> 的属性

`<Icon>` 的属性

`name`

`label`

`size`

`color`

`class`

`<Aside>` 的属性

`type`

`title`

`<FileTree>` 的属性

`<Steps>` 的属性

`<Card>` 的属性

`title`

`icon`

`<LinkCard>` 的属性

`title`

`href`

`description`

`<CardGrid>` 的属性

`stagger`

`<Badge>` 的属性

`text`

`variant`

`size`

`<LinkButton>` 的属性

`href`

`variant`

`icon`

`iconPlacement`

`<Tabs>` 的属性

`syncKey`

`<TabItem>` 的属性

`label`

`icon`

`引擎`

`语言`