Add more diagnostic help to error messages thrown by <Steps>

.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

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