Add tests and functionality for handling double quotes in file names in FileTree

docs/src/content/docs/components/file-tree.mdx

@@ -218,6 +218,49 @@ import { FileTree } from '@astrojs/starlight/components';
 
 </Preview>
 
+### Escape white-space in file names
+
+To include white-space in a file or directory name, escape it with double quotes.
+
+<Preview>
+
+```mdx {5,6}
+import { FileTree } from '@astrojs/starlight/components';
+
+<FileTree>
+
+- "main folder/" file <strong>container</strong>
+- "main folder/" file container
+  - "The Header.astro" main file
+  - …
+
+</FileTree>
+```
+
+<Fragment slot="markdoc">
+
+```markdoc {2,3}
+{% filetree %}
+- "main folder/" file <strong>container</strong>
+- "main folder/" file container
+  - "The Header.astro" main file
+  - …
+{% /filetree %}
+```
+
+</Fragment>
+
+<FileTree slot="preview">
+
+- "main folder/" file <strong>container</strong>
+- "main folder/" file container
+  - "The Header.astro" main file
+  - …
+
+</FileTree>
+
+</Preview>
+
 ## `<FileTree>` Props
 
 **Implementation:** [`FileTree.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/FileTree.astro)

packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts

@@ -84,6 +84,78 @@ describe('processor', () => {
 		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-comment-nodes.html');
 	});
 
+	test('double quotes allows to add white-space to file names', () => {
+		const html = processTestFileTree(`<ul><li>"file name"</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-file.html');
+	});
+
+	test('double quotes file name with text comments', () => {
+		const html = processTestFileTree(`<ul><li>"file name" with some comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-file-text.html');
+	});
+
+	test('double quotes file name with node comments', () => {
+		const html = processTestFileTree(`<ul><li>"file name" with <strong>important</strong> comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-file-node.html');
+	});
+
+	test('double quotes allows to add white-space to folder names', () => {
+		const html = processTestFileTree(`<ul><li>"folder name/"</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-folder.html');
+	});
+
+	test('double quotes folder name with text comments', () => {
+		const html = processTestFileTree(`<ul><li>"folder name/" with some comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-folder-text.html');
+	});
+
+	test('double quotes folder name with node comments', () => {
+		const html = processTestFileTree(`<ul><li>"folder name/" with <strong>important</strong> comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-folder-node.html');
+	});
+
+	test('special quotes allows to add white-space to file names', () => {
+		const html = processTestFileTree(`<ul><li>“file name”</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-file.html');
+	});
+
+	test('special quotes file name with text comments', () => {
+		const html = processTestFileTree(`<ul><li>“file name” with some comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-file-text.html');
+	});
+
+	test('special quotes file name with node comments', () => {
+		const html = processTestFileTree(`<ul><li>“file name” with <strong>important</strong> comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-file-node.html');
+	});
+
+	test('special quotes allows to add white-space to folder names', () => {
+		const html = processTestFileTree(`<ul><li>“folder name/”</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-folder.html');
+	});
+
+	test('special quotes folder name with text comments', () => {
+		const html = processTestFileTree(`<ul><li>“folder name/” with some comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-folder-text.html');
+	});
+
+	test('special quotes folder name with node comments', () => {
+		const html = processTestFileTree(`<ul><li>“folder name/” with <strong>important</strong> comments</li></ul>`);
+
+		expect(extractFileTree(html)).toMatchFileSnapshot('./snapshots/file-tree-double-quotes-folder-node.html');
+	});
+
 	test('identifies directory with either a file name ending with a slash or a nested list', () => {
 		const html = processTestFileTree(`<ul>
   <li>directory/</li>

packages/starlight/__tests__/remark-rehype/snapshots/file-tree-double-quotes-file-node.html

@@ -0,0 +1 @@
+<ul><li class="file"><span class="tree-entry"><span class=""><span><svg></svg></span>file name</span> <span class="comment">with <strong>important</strong> comments</span></span></li></ul>

packages/starlight/__tests__/remark-rehype/snapshots/file-tree-double-quotes-file-text.html

@@ -0,0 +1 @@
+<ul><li class="file"><span class="tree-entry"><span class=""><span><svg></svg></span>file name</span> <span class="comment">with some comments</span></span></li></ul>

packages/starlight/__tests__/remark-rehype/snapshots/file-tree-double-quotes-file.html

@@ -0,0 +1 @@
+<ul><li class="file"><span class="tree-entry"><span class=""><span><svg></svg></span>file name</span></span></li></ul>

packages/starlight/__tests__/remark-rehype/snapshots/file-tree-double-quotes-folder-node.html

@@ -0,0 +1 @@
+<ul><li class="directory"><details><summary><span class="tree-entry"><span class=""><span><span class="sr-only">Directory</span><svg></svg></span>folder name/</span> <span class="comment">with <strong>important</strong> comments</span></span></summary><ul><li class="file empty"><span class="tree-entry"><span class="">…</span></span></li></ul></details></li></ul>

packages/starlight/__tests__/remark-rehype/snapshots/file-tree-double-quotes-folder-text.html

@@ -0,0 +1 @@
+<ul><li class="directory"><details><summary><span class="tree-entry"><span class=""><span><span class="sr-only">Directory</span><svg></svg></span>folder name/</span> <span class="comment">with some comments</span></span></summary><ul><li class="file empty"><span class="tree-entry"><span class="">…</span></span></li></ul></details></li></ul>

packages/starlight/__tests__/remark-rehype/snapshots/file-tree-double-quotes-folder.html

@@ -0,0 +1 @@
+<ul><li class="directory"><details><summary><span class="tree-entry"><span class=""><span><span class="sr-only">Directory</span><svg></svg></span>folder name/</span></span></summary><ul><li class="file empty"><span class="tree-entry"><span class="">…</span></span></li></ul></details></li></ul>

packages/starlight/user-components/rehype-file-tree.ts

@@ -56,11 +56,10 @@ const fileTreeProcessor = rehype()
 
 				// Extract text comment that follows the file name, e.g. `README.md This is a comment`
 				if (firstChild?.type === 'text') {
-					const [filename, ...fragments] = firstChild.value.split(' ');
-					firstChild.value = filename || '';
-					const textComment = fragments.join(' ').trim();
-					if (textComment.length > 0) {
-						comment.push(fragments.join(' '));
+					const [filename, textComment] = splitFileNameAndTextComments(firstChild.value);
+					firstChild.value = filename;
+					if (textComment.trim().length > 0) {
+						comment.push(textComment);
 					}
 				}
 
@@ -244,6 +243,25 @@ function throwFileTreeValidationError(message: string): never {
 	);
 }
 
+function splitFileNameAndTextComments(value: string): [string, string] {
+	if (!value || value.trim() === '') return ['', ''];
+
+	// Handles the case where the file name is wrapped in double quotes, e.g. `"READ ME.md" This is a comment`.
+	if (value.startsWith('"')) {
+		const match = value.match(/^"([^"]+)"\s*(.*)$/);
+		if (match) return [match[1]!, match[2]!];
+	}
+
+	if (value.startsWith('“')) {
+		const match = value.match(/^“([^”]+)”\s*(.*)$/);
+		if (match) return [match[1]!, match[2]!];
+	}
+
+	const [filename, ...fragments] = value.split(' ');
+	const textComments = fragments.join(' ');
+	return [filename!, textComments];
+}
+
 export interface Definitions {
 	files: Record<string, string>;
 	extensions: Record<string, string>;