Refactor `<Steps>` counter (#2041)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

4 files changed, 28 insertions, 2 deletions

diff --git a/.changeset/strong-apes-burn.md b/.changeset/strong-apes-burn.md
new file mode 100644
index 00000000..1536b4cd
--- /dev/null
+++ b/.changeset/strong-apes-burn.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Fixes `<Steps>` numbering bug caused by Chrome v126 CSS counter rewrite
diff --git a/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts b/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts
index 36f4082c..273788e6 100644
--- a/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts
+++ b/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts
@@ -70,7 +70,7 @@ test('applies `role="list"` to child list', () => {
 test('does not interfere with other attributes on the child list', () => {
 	const { html } = processSteps('<ol start="5"><li>Step one</li></ol>');
 	expect(html).toMatchInlineSnapshot(
-		`"<ol start="5" role="list" class="sl-steps"><li>Step one</li></ol>"`
+		`"<ol start="5" role="list" class="sl-steps" style="--sl-steps-start: 4"><li>Step one</li></ol>"`
 	);
 });
 
@@ -87,3 +87,14 @@ test('applies class name and preserves existing classes on a child list', () =>
 		`"<ol class="test class-concat sl-steps" role="list"><li>Step one</li></ol>"`
 	);
 });
+
+test('applies custom property if start attribute is used', () => {
+	const start = 10;
+	const { html } = processSteps(`<ol start="${start}"><li>Step one</li></ol>`);
+	expect(html).toContain(`style="--sl-steps-start: ${start - 1}"`);
+});
+
+test('custom property for start count does not interfere with custom styles', () => {
+	const { html } = processSteps(`<ol start="20" style="color: red"><li>Step one</li></ol>`);
+	expect(html).toMatchInlineSnapshot(`"<ol start="20" style="--sl-steps-start: 19;color: red" role="list" class="sl-steps"><li>Step one</li></ol>"`);
+});
diff --git a/packages/starlight/user-components/Steps.astro b/packages/starlight/user-components/Steps.astro
index ffd65a35..66562555 100644
--- a/packages/starlight/user-components/Steps.astro
+++ b/packages/starlight/user-components/Steps.astro
@@ -13,10 +13,12 @@ const { html } = processSteps(content);
 		--bullet-margin: 0.375rem;
 
 		list-style: none;
+		counter-reset: steps-counter var(--sl-steps-start, 0);
 		padding-inline-start: 0;
 	}
 
 	.sl-steps > li {
+		counter-increment: steps-counter;
 		position: relative;
 		padding-inline-start: calc(var(--bullet-size) + 1rem);
 		/* HACK: Keeps any `margin-bottom` inside the `<li>`’s padding box to avoid gaps in the hairline border. */
@@ -31,7 +33,7 @@ const { html } = processSteps(content);
 
 	/* Custom list marker element. */
 	.sl-steps > li::before {
-		content: counter(list-item);
+		content: counter(steps-counter);
 		position: absolute;
 		top: 0;
 		inset-inline-start: 0;
diff --git a/packages/starlight/user-components/rehype-steps.ts b/packages/starlight/user-components/rehype-steps.ts
index ff9c9593..184df00e 100644
--- a/packages/starlight/user-components/rehype-steps.ts
+++ b/packages/starlight/user-components/rehype-steps.ts
@@ -44,6 +44,14 @@ const stepsProcessor = rehype()
 			} else {
 				rootElement.properties.className.push('sl-steps');
 			}
+
+			// Add the `start` attribute as a CSS custom property so we can use it as the starting index
+			// of the steps custom counter.
+			if (typeof rootElement.properties.start === 'number') {
+				const styles = [`--sl-steps-start: ${rootElement.properties.start - 1}`];
+				if (rootElement.properties.style) styles.push(String(rootElement.properties.style));
+				rootElement.properties.style = styles.join(';');
+			}
 		};
 	});