From d7a295e5f63171c7eee9fc11333157d8c7e6c803 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Matos?= <joao@tritao.eu>
Date: Wed, 18 Sep 2024 08:43:29 +0100
Subject: [PATCH] Fix broken restoration of remark directives. (#2327)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
---
 .changeset/gold-coats-destroy.md              |  5 +++
 .../__tests__/remark-rehype/asides.test.ts    | 32 +++++++++++++++++++
 packages/starlight/integrations/asides.ts     |  3 +-
 3 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/gold-coats-destroy.md

diff --git a/.changeset/gold-coats-destroy.md b/.changeset/gold-coats-destroy.md
new file mode 100644
index 0000000000..416391d637
--- /dev/null
+++ b/.changeset/gold-coats-destroy.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": patch
+---
+
+Fixes restoration of remark directives for nodes with custom data attached.
diff --git a/packages/starlight/__tests__/remark-rehype/asides.test.ts b/packages/starlight/__tests__/remark-rehype/asides.test.ts
index 88110f682a..cda21bb7b5 100644
--- a/packages/starlight/__tests__/remark-rehype/asides.test.ts
+++ b/packages/starlight/__tests__/remark-rehype/asides.test.ts
@@ -270,3 +270,35 @@ test('lets remark plugin injected by Starlight plugins handle text and leaf dire
 		"<p>This is a:test of a sentence with a TEXT FROM REMARK PLUGIN directive handled by another remark plugin and some other text:name[content]{key="val"} directives not handled by any plugin.</p>"
 	`);
 });
+
+test('does not transform back directive nodes with data', async () => {
+	const processor = await createMarkdownProcessor({
+		remarkPlugins: [
+			...starlightAsides({
+				starlightConfig,
+				astroConfig: {
+					root: new URL(import.meta.url),
+					srcDir: new URL('./_src/', import.meta.url),
+				},
+				useTranslations,
+			}),
+			// A custom remark plugin updating the node with data that should be consumed by rehype.
+			function customRemarkPlugin() {
+				return function transformer(tree: Root) {
+					visit(tree, (node) => {
+						if (node.type !== 'textDirective') return;
+						node.data ??= {};
+						node.data.hName = 'span';
+						node.data.hProperties = { class: `api` };
+					});
+				};
+			},
+			remarkDirectivesRestoration,
+		],
+	});
+
+	const res = await processor.render(`This method is available in the :api[thing] API.`);
+	expect(res.code).toMatchInlineSnapshot(
+		`"<p>This method is available in the <span class="api">thing</span> API.</p>"`
+	);
+});
diff --git a/packages/starlight/integrations/asides.ts b/packages/starlight/integrations/asides.ts
index d98e6a403a..7c4dfb74f2 100644
--- a/packages/starlight/integrations/asides.ts
+++ b/packages/starlight/integrations/asides.ts
@@ -227,7 +227,8 @@ export function remarkDirectivesRestoration() {
 			if (
 				index !== undefined &&
 				parent &&
-				(node.type === 'textDirective' || node.type === 'leafDirective')
+				(node.type === 'textDirective' || node.type === 'leafDirective') &&
+				node.data === undefined
 			) {
 				transformUnhandledDirective(node, index, parent);
 				return;