Allow asides titles to contain markdown formatting (#2126)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Essential Randomness <essential.randomn3ss@gmail.com>

.changeset/mean-tigers-hunt.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Adds support for markdown formatting in aside titles

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

@@ -70,6 +70,39 @@ Some text
 	});
 });
 
+describe('custom labels with nested markdown', () => {
+	test.each(['note', 'tip', 'caution', 'danger'])('%s with custom code label', async (type) => {
+		const label = 'Custom `code` Label';
+		const labelWithoutMarkdown = 'Custom code Label';
+		const labelHtml = 'Custom <code>code</code> Label';
+		const res = await processor.render(`
+:::${type}[${label}]
+Some text
+:::
+  `);
+		expect(res.code).includes(`aria-label="${labelWithoutMarkdown}"`);
+		expect(res.code).includes(`</svg>${labelHtml}</p>`);
+	});
+});
+
+describe('custom labels with doubly-nested markdown', () => {
+	test.each(['note', 'tip', 'caution', 'danger'])(
+		'%s with custom doubly-nested label',
+		async (type) => {
+			const label = 'Custom **strong with _emphasis_** Label';
+			const labelWithoutMarkdown = 'Custom strong with emphasis Label';
+			const labelHtml = 'Custom <strong>strong with <em>emphasis</em></strong> Label';
+			const res = await processor.render(`
+:::${type}[${label}]
+Some text
+:::
+  `);
+			expect(res.code).includes(`aria-label="${labelWithoutMarkdown}"`);
+			expect(res.code).includes(`</svg>${labelHtml}</p>`);
+		}
+	);
+});
+
 test('ignores unknown directive variants', async () => {
 	const res = await processor.render(`
 :::unknown

packages/starlight/integrations/asides.ts

@@ -2,14 +2,15 @@
 
 import type { AstroConfig, AstroIntegration, AstroUserConfig } from 'astro';
 import { h as _h, s as _s, type Properties } from 'hastscript';
-import type { Node, Paragraph as P, Parent, Root } from 'mdast';
+import type { Node, Paragraph as P, Parent, PhrasingContent, Root } from 'mdast';
 import {
 	type Directives,
 	directiveToMarkdown,
 	type TextDirective,
 	type LeafDirective,
 } from 'mdast-util-directive';
 import { toMarkdown } from 'mdast-util-to-markdown';
+import { toString } from 'mdast-util-to-string';
 import remarkDirective from 'remark-directive';
 import type { Plugin, Transformer } from 'unified';
 import { visit } from 'unist-util-visit';
@@ -156,16 +157,16 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 			// prop to <Aside>, so when we find a directive label, we store it for the title prop and
 			// remove the paragraph from the container’s children.
 			let title = t(`aside.${variant}`);
+			let titleNode: PhrasingContent[] = [{ type: 'text', value: title }];
 			const firstChild = node.children[0];
 			if (
 				firstChild?.type === 'paragraph' &&
 				firstChild.data &&
-				'directiveLabel' in firstChild.data
+				'directiveLabel' in firstChild.data &&
+				firstChild.children.length > 0
 			) {
-				const firstGrandChild = firstChild.children[0];
-				if (firstGrandChild?.type === 'text') {
-					title = firstGrandChild.value;
-				}
+				titleNode = firstChild.children;
+				title = toString(firstChild.children);
 				// The first paragraph contains a directive label, we can safely remove it.
 				node.children.splice(0, 1);
 			}
@@ -189,7 +190,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 							},
 							iconPaths[variant]
 						),
-						{ type: 'text', value: title },
+						...titleNode,
 					]),
 					h('section', { class: 'starlight-aside__content' }, node.children),
 				]

packages/starlight/package.json

@@ -200,6 +200,7 @@
     "hastscript": "^9.0.0",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
+    "mdast-util-to-string": "^4.0.0",
     "pagefind": "^1.0.3",
     "rehype": "^13.0.1",
     "rehype-format": "^5.0.0",