Skip to content

Commit

Permalink
Merge branch 'main' into synced-tabs
Browse files Browse the repository at this point in the history
  • Loading branch information
HiDeoo authored May 8, 2024
2 parents 65fb559 + 2bbed1b commit 1b15ed2
Show file tree
Hide file tree
Showing 12 changed files with 220 additions and 14 deletions.
5 changes: 5 additions & 0 deletions .changeset/breezy-cats-taste.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@astrojs/starlight': patch
---

Adds extra information to the errors thrown by the `<Steps>` component to help locate misformatted code
44 changes: 44 additions & 0 deletions docs/src/content/docs/zh-cn/guides/components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,50 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
</TabItem>
</Tabs>

#### 同步选项卡

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

页面上拥有相同的 `syncKey` 值的所有 `<Tabs>` 都将展示相同的活动标签。这使得你的读者只需选择一次(例如他们的操作系统或包管理器),就可以看到他们的选择反映在整个页面中。

若要同步相关的选项卡,请为每个 `<Tabs>` 组件添加相同的 `syncKey` 属性,并确保它们都使用相同的 `<TabItem>` 标签:

```mdx 'syncKey="constellations"'
# src/content/docs/example.mdx

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

_一些星座:_

<Tabs syncKey="星座">
<TabItem label="猎户座">Bellatrix, Rigel, Betelgeuse</TabItem>
<TabItem label="双子座">Pollux, Castor A, Castor B</TabItem>
</Tabs>

_一些系外行星:_

<Tabs syncKey="星座">
<TabItem label="猎户座">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem>
<TabItem label="双子座">Pollux b, HAT-P-24b, HD 50554 b</TabItem>
</Tabs>
```

以上代码在页面上生成了以下内容:

_一些星座:_

<Tabs syncKey="星座">
<TabItem label="猎户座">Bellatrix, Rigel, Betelgeuse</TabItem>
<TabItem label="双子座">Pollux, Castor A, Castor B</TabItem>
</Tabs>

_一些系外行星:_

<Tabs syncKey="星座">
<TabItem label="猎户座">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem>
<TabItem label="双子座">Pollux b, HAT-P-24b, HD 50554 b</TabItem>
</Tabs>

### 卡片

import { Card, CardGrid } from '@astrojs/starlight/components';
Expand Down
28 changes: 28 additions & 0 deletions docs/src/content/docs/zh-cn/guides/i18n.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,34 @@ Starlight 期望你在所有语言中创建等效的页面。例如,如果你

如果某种语言尚未提供翻译,Starlight 将为读者显示该页面的默认语言(通过 `defaultLocale` 设置)的内容。例如,如果你尚未创建关于你的法语版本,并且你的默认语言是英语,那么访问 `/fr/about` 的访问者将看到来自 `/en/about` 的英语内容,并显示该页面尚未翻译的通知。这有助于你在默认语言中添加内容,然后在翻译人员有时间时逐步翻译它。

## 翻译网站标题

默认情况下,Starlight 会为所有语言使用相同的站点标题。
如果你需要为每种语言自定义标题,你可以在 Starlight 的选项中将一个对象传递给 [`title`](/zh-cn/reference/configuration/#title-必填)

```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
integrations: [
starlight({
- title: 'My Docs',
+ title: {
+ en: 'My Docs',
+ 'zh-CN': '我的文档',
+ },
defaultLocale: 'en',
locales: {
en: { label: 'English' },
'zh-cn': { label: '简体中文', lang: 'zh-CN' },
},
}),
],
});
```

## 翻译 Starlight 的 UI

import LanguagesList from '~/components/languages-list.astro';
Expand Down
1 change: 1 addition & 0 deletions docs/src/content/docs/zh-cn/guides/pages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ import CustomComponent from './CustomComponent.astro';
- [`slug`](/zh-cn/reference/frontmatter/#slug) 属性不受支持,并且会根据自定义页面的 URL 自动设置。
- [`editUrl`](/zh-cn/reference/frontmatter/#editurl) 选项需要一个 URL 来显示编辑链接。
- 用于自定义页面如何在 [自动生成的链接组](/zh-cn/reference/configuration/#sidebar) 中显示的 [`sidebar`](/zh-cn/reference/frontmatter/#sidebar) frontmatter 属性不可用。使用 `<StarlightPage />` 组件的页面不是集合的一部分,不能添加到自动生成的侧边栏组中。
- [`draft`](/zh-cn/reference/frontmatter/#draft) 选项仅会显示页面为草稿的 [通知](/zh-cn/reference/overrides/#draftcontentnotice),但不会自动将其从生产版本中排除。

##### `sidebar`

Expand Down
14 changes: 13 additions & 1 deletion docs/src/content/docs/zh-cn/reference/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,22 @@ export default defineConfig({

### `title` (必填)

**类型:** `string`
**类型:** `string | Record<string, string>`

设置你的网站标题。将用于元数据和浏览器标签标题。

这个值可以是一个字符串,或者对于多语言网站,可以是一个包含每种不同语言值的对象。
当使用对象形式时,键必须是 BCP-47 标签(例如 `en``ar``zh-CN`):

```ts
starlight({
title: {
en: 'My delightful docs site',
de: 'Meine bezaubernde Dokumentationsseite',
},
});
```

### `description`

**类型:** `string`
Expand Down
15 changes: 15 additions & 0 deletions docs/src/content/docs/zh-cn/reference/frontmatter.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,21 @@ pagefind: false
---
```

### `draft`

**类型:** `boolean`
**默认值:** `false`

设置此页面是否应被视为草稿,并且不包含在 [生产版本](https://docs.astro.build/zh-cn/reference/cli-reference/#astro-build)[自动生成的链接组](/zh-cn/guides/sidebar/#自动生成的分组) 中。设置为 `true` 可将页面标记为草稿,并使其仅在开发过程中可见。

```md
---
# src/content/docs/example.md
# 从生产版本中排除此页面
draft: true
---
```

### `sidebar`

**类型:** [`SidebarConfig`](#sidebarconfig)
Expand Down
14 changes: 13 additions & 1 deletion docs/src/content/docs/zh-cn/reference/overrides.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,12 @@ Starlight 会将以下参数传递给你的自定义组件。

当前语言的根路径。对于默认语言来说是 `undefined`

#### `siteTitle`

**类型:** `string`

根据页面语言设置的网站标题。

#### `slug`

**类型:** `string`
Expand Down Expand Up @@ -218,7 +224,7 @@ entry: {
**默认组件:** [`Header.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Header.astro)

在每个页面顶部显示的导航栏组件。
默认实现显示了 [`<SiteTitle />`](#sitetitle)[`<Search />`](#search)[`<SocialIcons />`](#socialicons)[`<ThemeSelect />`](#themeselect)[`<LanguageSelect />`](#languageselect)
默认实现显示了 [`<SiteTitle />`](#sitetitle-1)[`<Search />`](#search)[`<SocialIcons />`](#socialicons)[`<ThemeSelect />`](#themeselect)[`<LanguageSelect />`](#languageselect)

#### `SiteTitle`

Expand Down Expand Up @@ -332,6 +338,12 @@ Starlight 的页面侧边栏负责显示当前页面的子标题的目录。

自定义实现应确保在 `<h1>` 元素上设置 `id="_top"`,就像默认实现中一样。

#### `DraftContentNotice`

**默认组件:** [`DraftContentNotice.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/DraftContentNotice.astro)

在开发过程中,当当前页面被标记为草稿时,向用户显示的通知。

#### `FallbackContentNotice`

**默认组件:** [`FallbackContentNotice.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/FallbackContentNotice.astro)
Expand Down
5 changes: 5 additions & 0 deletions docs/src/content/docs/zh-cn/resources/community-content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -124,5 +124,10 @@ import YouTubeGrid from '~/components/youtube-grid.astro';
title: 'Astro Starlight 文档模板(构建自定义 app 文档!)',
description: '在大约 5 分钟内启动并运行新的 Starlight 网站',
},
{
href: 'https://www.youtube.com/watch?v=12o7WxjAxjM',
title: '使用代理将 Starlight 文档包含在 Next.js 项目中',
description: '将 Starlight 设置为 Next.js 网站内的子目录项目',
},
]}
/>
28 changes: 24 additions & 4 deletions packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,36 @@ test('component with non-`<ol>` content throws an error', () => {
"[AstroUserError]:
The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found the following element: \`<p>\`.
Hint:
To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps"
To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps
Full HTML passed to \`<Steps>\`:
<p>A paragraph is not an ordered list</p>
"
`);
});

test('component with multiple children throws an error', () => {
expect(() => processSteps('<ol></ol><ol></ol>')).toThrowErrorMatchingInlineSnapshot(`
expect(() =>
processSteps(
'<ol><li>List item</li></ol><p>I intended this to be part of the same list item</p><ol><li>Other list item</li></ol>'
)
).toThrowErrorMatchingInlineSnapshot(`
"[AstroUserError]:
The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found multiple child elements: \`<ol>\`, \`<ol>\`.
The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found multiple child elements: \`<ol>\`, \`<p>\`, \`<ol>\`.
Hint:
To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps"
To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps
Full HTML passed to \`<Steps>\`:
<ol>
<li>List item</li>
</ol>
<p>I intended this to be part of the same list item</p>
<ol>
<li>Other list item</li>
</ol>
"
`);
});

Expand Down
1 change: 1 addition & 0 deletions packages/starlight/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,7 @@
"mdast-util-to-markdown": "^2.1.0",
"pagefind": "^1.0.3",
"rehype": "^13.0.1",
"rehype-format": "^5.0.0",
"remark-directive": "^3.0.0",
"unified": "^11.0.4",
"unist-util-visit": "^5.0.0",
Expand Down
26 changes: 18 additions & 8 deletions packages/starlight/user-components/rehype-steps.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,17 @@
import { AstroError } from 'astro/errors';
import type { Element, Root } from 'hast';
import { rehype } from 'rehype';
import rehypeFormat from 'rehype-format';
import type { VFile } from 'vfile';

const prettyPrintProcessor = rehype().data('settings', { fragment: true }).use(rehypeFormat);
const prettyPrintHtml = (html: string) =>
prettyPrintProcessor.processSync({ value: html }).toString();

const stepsProcessor = rehype()
.data('settings', { fragment: true })
.use(function steps() {
return (tree: Root) => {
return (tree: Root, vfile: VFile) => {
const rootElements = tree.children.filter((item): item is Element => item.type === 'element');
const [rootElement] = rootElements;

Expand All @@ -17,12 +23,14 @@ const stepsProcessor = rehype()
throw new StepsError(
'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found multiple child elements: ' +
rootElements.map((element: Element) => `\`<${element.tagName}>\``).join(', ') +
'.'
'.',
vfile.value.toString()
);
} else if (rootElement.tagName !== 'ol') {
throw new StepsError(
'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found the following element: ' +
`\`<${rootElement.tagName}>\`.`
`\`<${rootElement.tagName}>\`.`,
vfile.value.toString()
);
}

Expand All @@ -49,10 +57,12 @@ export const processSteps = (html: string | undefined) => {
};

class StepsError extends AstroError {
constructor(message: string) {
super(
message,
'To learn more about the `<Steps>` component, see https://starlight.astro.build/guides/components/#steps'
);
constructor(message: string, html?: string) {
let hint =
'To learn more about the `<Steps>` component, see https://starlight.astro.build/guides/components/#steps';
if (html) {
hint += '\n\nFull HTML passed to `<Steps>`:\n' + prettyPrintHtml(html);
}
super(message, hint);
}
}
53 changes: 53 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit 1b15ed2

Please sign in to comment.