Intermediate Guide to Blog Usage

May 17, 2025

Components

Using components

Components let you easily reuse a piece of UI or styling consistently. Examples might include a link card or a YouTube embed. Starlight supports the use of components in MDX and Markdoc files and provides some common components for you to use.

Learn more about building components in the Astro Docs.

Using a component in MDX

Section titled “Using a component in MDX”

You can use a component by importing it into your MDX file and then rendering it as a JSX tag. These look like HTML tags but start with an uppercase letter matching the name in your import statement:

1
---
2
title: Welcome to my docs
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>Components can also contain **nested content**.</CustomCard>

Because Starlight is powered by Astro, you can add support for components built with any supported UI framework (React, Preact, Svelte, Vue, Solid, and Alpine) in your MDX files. Learn more about using components in MDX in the Astro docs.

Using a component in Markdoc

Section titled “Using a component in Markdoc”

Add support for authoring content in Markdoc by following our Markdoc set-up guide.

Using the Starlight Markdoc preset, you can use Starlight’s built-in components with Markdoc’s {% %} tag syntax. Unlike MDX, components in Markdoc do not need to be imported. The following example renders Starlight’s card component in a Markdoc file:

1
---
2
title: Welcome to my docs
3
---
4

5
{% card title="Stars" icon="star" %}
6
Sirius, Vega, Betelgeuse
7
{% /card %}

See the Astro Markdoc integration documentation for more information on how to use components in Markdoc files.

Built-in components

Section titled “Built-in components”

Starlight provides built-in components for common documentation use cases. These components are available from the @astrojs/starlight/components package in MDX files and from the Starlight Markdoc preset in Markdoc files.

See the sidebar for a list of available components and how to use them.

Compatibility with Starlight’s styles

Section titled “Compatibility with Starlight’s styles”

Starlight applies default styling to your Markdown content, for example, adding margin between elements. If these styles conflict with your component’s appearance, set the not-content class on your component to disable them.

1
<div class="not-content">
2
  <p>Not impacted by Starlight’s default content styling.</p>
3
</div>

Component props

Section titled “Component props”

Use the ComponentProps type from astro/types to reference the Props accepted by a component even if they are not exported by the component itself. This can be helpful when wrapping or extending an existing component.

The following example uses ComponentProps to get the type of the props accepted by Starlight’s built-in Badge component:

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

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

Icons

Display Icons

To display icons from Starlight’s built-in icon set, use the <Icon> component.

Import Icons

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

Icon Usage

Display an icon using the <Icon> component. An icon requires a name set to one of Starlight’s built-in icons and can optionally include a label to provide context for screen readers.

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

Preview

Customize icons

The size and color attributes can be used to adjust the icon’s appearance using CSS units and color values. The class attribute can be used to add custom CSS classes to the icon.

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)" /%}

Preview

`<Icon>` Props

Implementation: Icon.astro

The <Icon> component accepts the following props:

`name`

Section titled “name”

required type: StarlightIcon

The name of the icon to display set to one of Starlight’s built-in icons.

`label`

Section titled “label”

type: string

An optional label to provide context for assistive technologies, such as screen readers.

When label is not set, the icon will be completely hidden from assistive technologies. In this case, make sure the context is still understandable without the icon. For example, a link containing only the icon must include the label attribute in order to be accessible, but if a link contains text and the icon is purely decorative, omitting the label may make sense.

`size`

Section titled “size”

type: string

The size of the icon using CSS units.

`color`

Section titled “color”

type: string

The color of the icon using a CSS color value.

`class`

Section titled “class”

type: string

Custom CSS classes to add to the icon.

All icons

A list of all available icons is shown below with their associated names. Click an icon to copy its name to your clipboard.

Asides

Show Asides

To display secondary information alongside a page’s main content, use the <Aside> component.

Import Asides

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

Asides Usage

Display an aside (also known as “admonitions” or “callouts”) using the <Aside> component.

An <Aside> can have an optional type attribute, which controls the aside’s color, icon, and default title.

MDX
Markdoc

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

3
<Aside>Some content in an aside.</Aside>
4

5
<Aside type="caution">Some cautionary content.</Aside>
6

7
<Aside type="tip">
8

9
Other content is also supported in asides.
10

11
```js
12
// A code snippet, for example.
13
```
14

15
</Aside>
16

17
<Aside type="danger">Do not give your password to anyone.</Aside>

1
{% aside %}
2
Some content in an aside.
3
{% /aside %}
4

5
{% aside type="caution" %}
6
Some cautionary content.
7
{% /aside %}
8

9
{% aside type="tip" %}
10
Other content is also supported in asides.
11

12
```js
13
// A code snippet, for example.
14
```
15
{% /aside %}
16

17
{% aside type="danger" %}
18
Do not give your password to anyone.
19
{% /aside %}

Preview

Starlight also provides a custom syntax for rendering asides in Markdown and MDX as an alternative to the <Aside> component. See the “Authoring Content in Markdown” guide for details of the custom syntax.

Use custom titles

Override the default aside titles by using the title attribute.

MDX
Markdoc

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

3
<Aside type="caution" title="Watch out!">
4
  A warning aside *with* a custom title.
5
</Aside>

1
{% aside type="caution" title="Watch out!" %}
2
A warning aside *with* a custom title.
3
{% /aside %}

Preview

`<Aside>` Props

Implementation: Aside.astro

The <Aside> component accepts the following props:

`type`

type: 'note' | 'tip' | 'caution' | 'danger'
default: 'note'

The type of aside to display:

note asides (the default) are blue and display an information icon.
tip asides are purple and display a rocket icon.
caution asides are yellow and display a triangular warning icon.
danger asides are red and display an octagonal warning icon.

`title`

type: string

The title of the aside to display. If title is not set, the default title for the current aside type will be used.

文件树

显示文件树

要显示带有文件图标和可折叠子目录的目录结构，请使用 <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
Directorysrc
- Directorycomponents
  - Header.astro
- …
Directorypages/
- …

文件树导入

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
Directorysrc
- Directorycomponents
  - Header.astro
  - Title.astro
- Directorypages/
  - …

高亮显示条目

通过将文件或目录的名称加粗，来使文件或目录从中脱颖而出，例如 **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 %}

预览

Directorysrc
- Directorycomponents
  - 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 %}

预览

Directorysrc
- Directorycomponents
  - 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 %}

预览

Directorysrc
- Directorycomponents
  - 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 数组中。

Intermediate Guide to Blog Usage

Components

Using components

Using a component in MDX

Using a component in Markdoc

Built-in components

Compatibility with Starlight’s styles

Component props

Icons

Display Icons

Import Icons

Icon Usage

Customize icons

<Icon> Props

name

label

size

color

class

All icons

Asides

Show Asides

Import Asides

Asides Usage

Use custom titles

<Aside> Props

type

title

文件树

显示文件树

文件树导入

文件树用法

高亮显示条目

添加注释

添加占位符

<FileTree> 的属性

步骤

显示步骤

步骤导入

步骤用法

<Steps> 的属性

卡片

导入卡片

卡片用法

为卡片添加图标

分组卡片

<Card> 的属性

title

icon

链接卡片

卡片导入

卡片用法

添加链接描述

分组链接卡片

<LinkCard> 的属性

title

href

description

卡片网格

卡片导入

卡片用法

分组卡片

分组链接卡片

交错卡片

<CardGrid> 的属性

stagger

徽章

徽章导入

徽章用法

使用不同的尺寸

自定义徽章

<Badge> 的属性

text

variant

size

链接按钮

链接按钮导入

链接按钮用法

向链接按钮添加图标

<LinkButton> 的属性

`<Icon>` Props

`name`

`label`

`size`

`color`

`class`

`<Aside>` Props

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

`引擎`

`语言`