在 Markdown 中编写内容
Starlight 在 .md
文件中支持Markdown 的全部语法,以及用于定义标题和描述等元数据的 frontmatter YAML。
如果使用 MDX 或 Markdoc 文件格式,请务必查看 MDX 文档或 Markdoc 文档,因为它们对 Markdown 的支持和用法可能有所不同。
Frontmatter
标题为“Frontmatter”的部分你可以通过在 Starlight 页面的 frontmatter 中设置值来自定义单个页面。Frontmatter 设置在文件的顶部,位于 ---
分隔符之间。
---title: My page title---
Page content follows the second `---`.
每个页面都必须至少包含一个 title
。请参阅 frontmatter 参考,了解所有可用字段以及如何添加自定义字段。
内联样式
标题为“内联样式”的部分文本可以是粗体、斜体或删除线。
Text can be **bold**, _italic_, or ~~strikethrough~~.
你可以链接到另一个页面。
You can [link to another page](/getting-started/).
你可以用反引号高亮显示内联代码
。
You can highlight `inline code` with backticks.
Starlight 中的图片使用了 Astro 内置的优化资源支持。
Markdown 和 MDX 支持用于显示图片的 Markdown 语法,其中包括为屏幕阅读器和辅助技术提供的 alt 文本。

对于本地存储在项目中的图片,也支持相对图片路径。

你可以使用标题来组织内容。在 Markdown 中,标题由行首的若干个 #
表示。
如何在 Starlight 中组织页面内容
标题为“如何在 Starlight 中组织页面内容”的部分Starlight 被配置为自动使用你的页面标题作为顶级标题,并将在每个页面的目录顶部包含一个“概览”标题。我们建议每个页面都以常规段落文本内容开始,并使用 <h2>
及更低级别的页内标题。
---title: Markdown Guidedescription: How to use Markdown in Starlight---
This page describes how to use Markdown in Starlight.
## Inline Styles
## Headings
自动标题锚点链接
标题为“自动标题锚点链接”的部分在 Markdown 中使用标题会自动为你生成锚点链接,这样你就可以直接链接到页面的特定部分。
---title: My page of contentdescription: How to use Starlight's built-in anchor links---
## Introduction
I can link to [my conclusion](#conclusion) lower on the same page.
## Conclusion
`https://my-site.com/page1/#introduction` navigates directly to my Introduction.
二级(<h2>
)和三级(<h3>
)标题将自动出现在页面目录中。
在 Astro 文档中了解更多关于 Astro 如何处理标题 id
的信息。
侧栏(也称为“admonitions”或“callouts”)对于在页面主要内容旁边显示次要信息非常有用。
Starlight 提供了一种自定义的 Markdown 语法来渲染侧栏。侧栏块由一对三冒号 :::
包裹你的内容,可以是 note
、tip
、caution
或 danger
类型。
你可以在侧栏中嵌套任何其他 Markdown 内容类型,但侧栏最适合用于简短扼要的内容块。
注释侧栏
标题为“注释侧栏”的部分:::noteStarlight is a documentation website toolkit built with [Astro](https://astro.js.cn/). You can get started with this command:
```shnpm create astro@latest -- --template starlight```
:::
自定义侧栏标题
标题为“自定义侧栏标题”的部分你可以在侧栏类型后的方括号中为侧栏指定一个自定义标题,例如 :::tip[你知道吗?]
。
:::tip[Did you know?]Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.js.cn/en/concepts/islands/).:::
自定义侧栏图标
标题为“自定义侧栏图标”的部分你可以在侧栏类型或自定义标题后的大括号中为侧栏指定一个自定义图标,例如 :::tip{icon="heart"}
或 :::tip[你知道吗?]{icon="heart"}
。图标名称必须设置为 Starlight 的一个内置图标的名称。
:::tip{icon="heart"}Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.js.cn/en/concepts/islands/).:::
更多侧栏类型
标题为“更多侧栏类型”的部分“警告”和“危险”类型的侧栏有助于吸引用户注意那些可能让他们出错的细节。如果你发现自己经常使用这些,那也可能表明你正在文档化的东西需要重新设计。
:::cautionIf you are not sure you want an awesome docs site, think twice before using [Starlight](/).:::
:::dangerYour users may be more productive and find your product easier to use thanks to helpful Starlight features.
- Clear navigation- User-configurable colour theme- [i18n support](/guides/i18n/)
:::
块级引用
标题为“块级引用”的部分这是一个块级引用,通常用于引用他人或文档。
块级引用通过在每行开头使用
>
来表示。
> This is a blockquote, which is commonly used when quoting another person or document.>> Blockquotes are indicated by a `>` at the start of each line.
代码块
标题为“代码块”的部分代码块由开头和结尾的三个反引号 ```
包裹。你可以在开头的反引号后指定所使用的编程语言。
// Javascript code with syntax highlighting.var fun = function lang(l) { dateformat.i18n = require('./lang/' + l); return true;};
```js// Javascript code with syntax highlighting.var fun = function lang(l) { dateformat.i18n = require('./lang/' + l); return true;};```
Expressive Code 功能
标题为“Expressive Code 功能”的部分Starlight 使用 Expressive Code 来扩展代码块的格式化功能。Expressive Code 的文本标记和窗口框架插件默认启用。代码块的渲染可以通过 Starlight 的 expressiveCode
配置选项进行配置。
文本标记
标题为“文本标记”的部分你可以使用代码块首行的 Expressive Code 文本标记来高亮显示代码块的特定行或部分。使用花括号({ }
)高亮整行,使用引号高亮文本字符串。
有三种高亮样式:中性色用于引起对代码的注意,绿色用于表示插入的代码,红色用于表示删除的代码。文本和整行都可以使用默认标记,或与 ins=
和 del=
结合使用以产生所需的高亮效果。
Expressive Code 提供了多种选项来定制代码示例的视觉外观。其中许多选项可以组合使用,以创建极具说明性的代码示例。请查阅 Expressive Code 文档以了解所有可用的丰富选项。下面展示了一些最常见的示例:
-
function demo() {// This line (#2) and the next one are highlightedreturn 'This is line #3 of this snippet';}```js {2-3}function demo() {// This line (#2) and the next one are highlightedreturn 'This is line #3 of this snippet';}``````js {% meta="{2-3}" %}function demo() {// This line (#2) and the next one are highlightedreturn 'This is line #3 of this snippet';}```
-
// Individual terms can be highlighted, toofunction demo() {return 'Even regular expressions are supported';}```js "Individual terms" /Even.*supported/// Individual terms can be highlighted, toofunction demo() {return 'Even regular expressions are supported';}``````js {% meta="'Individual terms' /Even.*supported/" %}// Individual terms can be highlighted, toofunction demo() {return 'Even regular expressions are supported';}```
-
function demo() {console.log('These are inserted and
deletedmarker types');// The return statement uses the default marker typereturn true;}```js "return true;" ins="inserted" del="deleted"function demo() {console.log('These are inserted and deleted marker types');// The return statement uses the default marker typereturn true;}``````js {% meta="'return true;' ins='inserted' del='deleted'" %}function demo() {console.log('These are inserted and deleted marker types');// The return statement uses the default marker typereturn true;}``` -
function thisIsJavaScript() {// This entire block gets highlighted as JavaScript,// and we can still add diff markers to it!console.log('Old code to be removed')console.log('New and shiny code!')}```diff lang="js"function thisIsJavaScript() {// This entire block gets highlighted as JavaScript,// and we can still add diff markers to it!- console.log('Old code to be removed')+ console.log('New and shiny code!')}``````diff {% meta="lang='js'" %}function thisIsJavaScript() {// This entire block gets highlighted as JavaScript,// and we can still add diff markers to it!- console.log('Old code to be removed')+ console.log('New and shiny code!')}```
框架和标题
标题为“框架和标题”的部分代码块可以渲染在一个类似窗口的框架内。对于 shell 脚本语言(例如 bash
或 sh
),将使用一个看起来像终端窗口的框架。如果其他语言包含标题,则会显示在代码编辑器风格的框架内。
代码块的可选标题可以通过在代码块的起始反引号和语言标识符后添加 title="..."
属性,或者在代码的前几行中使用文件名注释来设置。
-
my-test-file.js console.log('Hello World!');```js// my-test-file.jsconsole.log('Hello World!');``````js// my-test-file.jsconsole.log('Hello World!');``` -
正在安装依赖…… npm install```bash title="Installing dependencies…"npm install``````bash {% title="Installing dependencies…" %}npm install``` -
echo "This is not rendered as a terminal despite using the bash language"```bash frame="none"echo "This is not rendered as a terminal despite using the bash language"``````bash {% frame="none" %}echo "This is not rendered as a terminal despite using the bash language"```
详细信息
标题为“详细信息”的部分详细信息(也称为“disclosure”或“accordion”)对于隐藏非即时相关的内容非常有用。用户可以点击一个简短的摘要来展开和查看完整内容。
在你的 Markdown 内容中使用标准的 HTML <details>
和 <summary>
元素来创建一个可展开/折叠的小部件。
你可以在 <details>
元素内嵌套任何其他 Markdown 语法。
仙女座星系在何时何地最容易看到?
仙女座星系在 11 月份的夜空中最容易看到,可见纬度范围在 +90°
到 −40°
之间。
<details><summary>Where and when is the Andromeda constellation most visible?</summary>
The [Andromeda constellation](<https://en.wikipedia.org/wiki/Andromeda_(constellation)>) is most visible in the night sky during the month of November at latitudes between `+90°` and `−40°`.
</details>
其他常见的 Markdown 功能
标题为“其他常见的 Markdown 功能”的部分Starlight 支持所有其他的 Markdown 编写语法,例如列表和表格。请参阅 Markdown 指南的 Markdown 速查表,快速了解所有 Markdown 语法元素。
高级 Markdown 和 MDX 配置
标题为“高级 Markdown 和 MDX 配置”的部分Starlight 使用了基于 remark 和 rehype 构建的 Astro 的 Markdown 和 MDX 渲染器。你可以通过在 Astro 配置文件中添加 remarkPlugins
或 rehypePlugins
来增加对自定义语法和行为的支持。请参阅 Astro 文档中的“Markdown 插件”以了解更多信息。
Markdoc
标题为“Markdoc”的部分Starlight 支持使用实验性的 Astro Markdoc 集成和 Starlight Markdoc 预设来编写 Markdoc 内容。
使用 Markdoc 创建新项目
标题为“使用 Markdoc 创建新项目”的部分使用 create astro
启动一个预配置了 Markdoc 的新 Starlight 项目。
npm create astro@latest -- --template starlight/markdoc
pnpm create astro --template starlight/markdoc
yarn create astro --template starlight/markdoc
将 Markdoc 添加到现有项目
标题为“将 Markdoc 添加到现有项目”的部分如果你已经有一个 Starlight 站点并想添加 Markdoc,请按照以下步骤操作。
-
添加 Astro 的 Markdoc 集成
终端窗口 npx astro add markdoc终端窗口 pnpm astro add markdoc终端窗口 yarn astro add markdoc -
安装 Starlight Markdoc 预设
终端窗口 npm install @astrojs/starlight-markdoc终端窗口 pnpm add @astrojs/starlight-markdoc终端窗口 yarn add @astrojs/starlight-markdoc -
在
markdoc.config.mjs
创建一个 Markdoc 配置文件,并使用 Starlight Markdoc 预设。import { defineMarkdocConfig } from '@astrojs/markdoc/config';import starlightMarkdoc from '@astrojs/starlight-markdoc';export default defineMarkdocConfig({extends: [starlightMarkdoc()],});
要了解更多关于 Markdoc 语法和功能的信息,请参阅 Markdoc 文档或 Astro Markdoc 集成指南。
配置 Markdoc 预设
标题为“配置 Markdoc 预设”的部分starlightMarkdoc()
预设接受以下配置选项。
headingLinks
标题为“headingLinks”的部分类型: boolean
默认值: true
控制标题是否渲染为可点击的锚点链接。等同于 markdown.headingLinks
选项,该选项适用于 Markdown 和 MDX 文件。
export default defineMarkdocConfig({ // Disable the default heading anchor link support extends: [starlightMarkdoc({ headingLinks: false })],});