Skip to content

Commit dd8b096

Browse files
HiDeooHiDeoo
authored
Merge branch 'main' into update-config-0413
2 parents 3caac4f + 82a584f commit dd8b096

9 files changed

Lines changed: 502 additions & 43 deletions

File tree

‎docs/src/content/docs/zh-cn/components/badges.mdx‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -33,31 +33,31 @@ import { Badge } from '@astrojs/starlight/components';
3333
```mdx
3434
import { Badge } from '@astrojs/starlight/components';
3535

36-
<Badge text="注释" variant="note" />
37-
<Badge text="成功" variant="success" />
38-
<Badge text="提示" variant="tip" />
39-
<Badge text="注意" variant="caution" />
40-
<Badge text="危险" variant="danger" />
36+
- <Badge text="注释" variant="note" />
37+
- <Badge text="成功" variant="success" />
38+
- <Badge text="提示" variant="tip" />
39+
- <Badge text="注意" variant="caution" />
40+
- <Badge text="危险" variant="danger" />
4141
```
4242

4343
<Fragment slot="markdoc">
4444

4545
```markdoc
46-
{% badge text="注释" variant="note" /%}
47-
{% badge text="成功" variant="success" /%}
48-
{% badge text="提示" variant="tip" /%}
49-
{% badge text="注意" variant="caution" /%}
50-
{% badge text="危险" variant="danger" /%}
46+
- {% badge text="注释" variant="note" /%}
47+
- {% badge text="成功" variant="success" /%}
48+
- {% badge text="提示" variant="tip" /%}
49+
- {% badge text="注意" variant="caution" /%}
50+
- {% badge text="危险" variant="danger" /%}
5151
```
5252

5353
</Fragment>
5454

5555
<Fragment slot="preview">
56-
<Badge text="注释" variant="note" />
57-
<Badge text="成功" variant="success" />
58-
<Badge text="提示" variant="tip" />
59-
<Badge text="注意" variant="caution" />
60-
<Badge text="危险" variant="danger" />
56+
- <Badge text="注释" variant="note" />
57+
- <Badge text="成功" variant="success" />
58+
- <Badge text="提示" variant="tip" />
59+
- <Badge text="注意" variant="caution" />
60+
- <Badge text="危险" variant="danger" />
6161
</Fragment>
6262

6363
</Preview>
@@ -71,25 +71,25 @@ import { Badge } from '@astrojs/starlight/components';
7171
```mdx /size="\w+"/
7272
import { Badge } from '@astrojs/starlight/components';
7373

74-
<Badge text="新" size="small" />
75-
<Badge text="更新更强" size="medium" />
76-
<Badge text="更新更强更逼格" size="large" />
74+
- <Badge text="新" size="small" />
75+
- <Badge text="更新更强" size="medium" />
76+
- <Badge text="更新更强更逼格" size="large" />
7777
```
7878

7979
<Fragment slot="markdoc">
8080

8181
```markdoc /size="\w+"/
82-
{% badge text="新" size="small" /%}
83-
{% badge text="更新更强" size="medium" /%}
84-
{% badge text="更新更强更逼格" size="large" /%}
82+
- {% badge text="新" size="small" /%}
83+
- {% badge text="更新更强" size="medium" /%}
84+
- {% badge text="更新更强更逼格" size="large" /%}
8585
```
8686

8787
</Fragment>
8888

8989
<Fragment slot="preview">
90-
<Badge text="新" size="small" />
91-
<Badge text="更新更强" size="medium" />
92-
<Badge text="更新更强更逼格" size="large" />
90+
- <Badge text="新" size="small" />
91+
- <Badge text="更新更强" size="medium" />
92+
- <Badge text="更新更强更逼格" size="large" />
9393
</Fragment>
9494

9595
</Preview>

‎docs/src/content/docs/zh-cn/guides/customization.mdx‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -198,10 +198,15 @@ defineConfig({
198198

199199
Starlight 内置了对通过 Starlight 集成中的 [`social`](/zh-cn/reference/configuration/#social) 选项将链接添加到网站标题的社交媒体账户的支持。
200200

201-
你可以在 [配置参考](/zh-cn/reference/configuration/#social) 中找到完整的支持链接图标列表。
202-
如果你需要支持其他服务，请在 GitHub 或 Discord 上告诉我们！
201+
`social`数组中的每个条目都必须是具有以下三个属性的对象：
203202

204-
```js {9-12}
203+
- `icon`：Starlight [内置的图标](/zh-cn/reference/icons/)之一，例如 `"github"`。
204+
- `label`：链接的可访问标签，例如 `"GitHub"`。
205+
- `href`: 链接的 URL，例如 `"https://github.com/withastro/starlight"`。
206+
207+
以下示例添加了指向 Astro Discord 和 Starlight GitHub 仓库的链接：
208+
209+
```js {9-16}
205210
// astro.config.mjs
206211
import { defineConfig } from 'astro/config';
207212
import starlight from '@astrojs/starlight';
@@ -210,10 +215,14 @@ export default defineConfig({
210215
integrations: [
211216
starlight({
212217
title: '带有社交链接的页面',
213-
social: {
214-
discord: 'https://astro.build/chat',
215-
github: 'https://github.com/withastro/starlight',
216-
},
218+
social: [
219+
{ icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
220+
{
221+
icon: 'github',
222+
label: 'GitHub',
223+
href: 'https://github.com/withastro/starlight',
224+
},
225+
],
217226
}),
218227
],
219228
});

‎docs/src/content/docs/zh-cn/guides/route-data.mdx‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: 路由数据
3+
description: 了解 Starlight 的页面数据模型是如何用于渲染你的页面以及如何自定义它。
4+
---
5+
6+
import { Steps } from '@astrojs/starlight/components';
7+
8+
当 Starlight 渲染文档中的页面时，它首先创建一个路由数据对象来表示该页面上的内容。
9+
本指南解释了路由数据是如何生成的，如何使用它，以及如何自定义它来修改Starlight的默认行为。
10+
11+
有关可用属性的完整列表，请参阅 [“路由数据参考”](/zh-cn/reference/route-data/)。
12+
13+
## 什么是路由数据？
14+
15+
Starlight 路由数据是一个包含渲染单个页面所需的所有信息的对象。
16+
它包括当前页面的信息以及从你的 Starlight 配置生成的数据。
17+
18+
## 使用路由数据
19+
20+
Starlight 的所有组件都使用路由数据来决定为每个页面渲染什么。
21+
例如，[`siteTitle`](/zh-cn/reference/route-data/#sitetitle) 字符串用于显示网站标题，[`sidebar`](/zh-cn/reference/route-data/#sidebar) 数组用于渲染全局侧边栏导航。
22+
23+
你可以在 Astro 组件中通过 `Astro.locals.starlightRoute` 全局变量访问这些数据：
24+
25+
```astro title="example.astro" {2}
26+
---
27+
const { siteTitle } = Astro.locals.starlightRoute;
28+
---
29+
30+
<p>此网站的页面标题是 “{siteTitle}”</p>
31+
```
32+
33+
例如，在 [重写组件](/zh-cn/guides/overriding-components/) 以自定义显示内容时，这会很有用。
34+
35+
## 自定义路由数据
36+
37+
Starlight 的路由数据是开箱即用的，不需要任何配置。但是，对于高级用例，你可能需要自定义某些或所有页面的路由数据，以修改你的网站显示方式。
38+
39+
这与 [重写组件](/zh-cn/guides/overriding-components/) 的概念类似，但不是修改 Starlight 渲染数据的方式，而是修改 Starlight 渲染的数据。
40+
41+
### 什么时候自定义路由数据
42+
43+
当你希望以现有配置选项无法实现的方式修改 Starlight 处理数据的方式时，自定义路由数据会很有用。
44+
45+
例如，你可能想要过滤侧边栏项目或自定义特定页面的标题。
46+
像这样的更改不需要修改 Starlight 的默认组件，只需要传递给这些组件的数据。
47+
48+
### 如何自定义路由数据
49+
50+
你可以使用一种特殊形式的 “中间件” 来自定义路由数据。
51+
这是一个每次 Starlight 渲染页面时都会调用的函数，可以修改路由数据对象中的值。
52+
53+
<Steps>
54+
55+
1. 创建一个新文件，使用 Starlight 的 `defineRouteMiddleware()` 工具函数导出一个 `onRequest` 函数：
56+
57+
```ts
58+
// src/routeData.ts
59+
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
60+
61+
export const onRequest = defineRouteMiddleware(() => {});
62+
```
63+
64+
2. 告诉 Starlight 你的路由数据中间件文件在 `astro.config.mjs` 中的位置：
65+
66+
```js ins={9}
67+
// astro.config.mjs
68+
import { defineConfig } from 'astro/config';
69+
import starlight from '@astrojs/starlight';
70+
71+
export default defineConfig({
72+
integrations: [
73+
starlight({
74+
title: 'My delightful docs site',
75+
routeMiddleware: './src/routeData.ts',
76+
}),
77+
],
78+
});
79+
```
80+
81+
3. 更新你的 `onRequest` 函数来修改路由数据。
82+
83+
你的中间件接收的第一个参数是 [Astro 的上下文对象](https://docs.astro.build/zh-cn/reference/api-reference/)。
84+
它包含关于当前页面渲染的完整信息，包括当前 URL 和 `locals`。
85+
86+
在这个例子中，我们将在每页标题的末尾添加一个感叹号，使我们的文档更加精彩。
87+
88+
```ts
89+
// src/routeData.ts
90+
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
91+
92+
export const onRequest = defineRouteMiddleware((context) => {
93+
// 获取此页面的内容集合条目。
94+
const { entry } = context.locals.starlightRoute;
95+
// 更新标题以添加感叹号。
96+
entry.data.title = entry.data.title + '!';
97+
});
98+
```
99+
100+
</Steps>
101+
102+
#### 多个路由中间件
103+
104+
Starlight 还支持提供多个中间件。
105+
将 `routeMiddleware` 设置为路径数组，以添加多个中间件处理程序：
106+
107+
```js {9}
108+
// astro.config.mjs
109+
import { defineConfig } from 'astro/config';
110+
import starlight from '@astrojs/starlight';
111+
112+
export default defineConfig({
113+
integrations: [
114+
starlight({
115+
title: 'My site with multiple middleware',
116+
routeMiddleware: ['./src/middleware-one.ts', './src/middleware-two.ts'],
117+
}),
118+
],
119+
});
120+
```
121+
122+
#### 等待稍后的路由中间件
123+
124+
为了在执行代码之前等待堆栈中稍后的中间件运行，你可以等待作为第二个参数传递给中间件函数的 `next()` 回调。这对于等待插件的中间件运行后再进行更改非常有用。
125+
126+
```ts "next" "await next();"
127+
// src/routeData.ts
128+
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
129+
130+
export const onRequest = defineRouteMiddleware(async (context, next) => {
131+
// 等待后续中间件运行。
132+
await next();
133+
// 修改路由数据
134+
const { entry } = context.locals.starlightRoute;
135+
entry.data.title = entry.data.title + '!';
136+
});
137+
```

‎docs/src/content/docs/zh-cn/reference/overrides.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,9 @@ tableOfContents:
2222
**默认组件：** [`Head.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Head.astro)
2323

2424
在每个页面的 `<head>` 元素内渲染的组件。
25-
包含 `<title>` 和 `<meta charset="utf-8">` 等重要标签。
2625

2726
重写此组件应作为最后手段。
28-
如果可能，请优先使用 Starlight 配置中的 [`head`](/zh-cn/reference/configuration/#head) 选项。
27+
如果可能，请优先使用 [`head` 配置项](/zh-cn/reference/configuration/#head)，[`head` frontmatter 字段](/zh-cn/reference/frontmatter/#head)，或者使用 [路由数据中间件](/zh-cn/guides/route-data/#自定义路由数据) 来自定义默认组件渲染的路由数据。
2928

3029
#### `ThemeProvider`
3130

‎docs/src/content/docs/zh-cn/reference/plugins.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -163,19 +163,23 @@ declare namespace StarlightApp {
163163
要更新嵌套的配置值，你必须提供整个嵌套对象。
164164

165165
要扩展现有的配置选项而不是覆盖它，可以将现有值展开到新值中。
166-
在下面的例子中，通过将 `config.social` 展开到新的 `social` 对象中，向现有配置添加了一个新的 [`social`](/zh-cn/reference/configuration/#social) 媒体账号：
166+
在下面的例子中，通过将 `config.social` 展开到新的 `social` 数组中，向现有配置添加了一个新的 [`social`](/zh-cn/reference/configuration/#social) 媒体账号：
167167

168-
```ts {6-11}
168+
```ts {6-15}
169169
// plugin.ts
170170
export default {
171171
name: 'add-twitter-plugin',
172172
hooks: {
173173
'config:setup'({ config, updateConfig }) {
174174
updateConfig({
175-
social: {
175+
social: [
176176
...config.social,
177-
twitter: 'https://twitter.com/astrodotbuild',
178-
},
177+
{
178+
icon: 'twitter',
179+
label: 'Twitter',
180+
href: 'https://twitter.com/astrodotbuild',
181+
},
182+
],
179183
});
180184
},
181185
},

0 commit comments

Comments
 (0)