Merge branch 'main' into object-title-docs

.changeset/breezy-cats-taste.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Adds extra information to the errors thrown by the `<Steps>` component to help locate misformatted code

docs/src/content/docs/zh-cn/guides/components.mdx

@@ -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';

docs/src/content/docs/zh-cn/resources/community-content.mdx

@@ -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 网站内的子目录项目',
+		},
 	]}
 />

packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts

@@ -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>
+			"
 	`);
 });
 

packages/starlight/package.json

@@ -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",

packages/starlight/user-components/rehype-steps.ts

@@ -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;
 
@@ -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()
 				);
 			}
 
@@ -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);
 	}
 }