Relax remark/rehype plugins usage (#3332)

Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

Author: HiDeoo

.changeset/pink-queens-remain.md

@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds a new [`markdown.processedDirs`](https://starlight.astro.build/reference/configuration/#processeddirs) configuration option to specify additional directories where files should be processed by Starlight’s Markdown pipeline.
+
+By default, Starlight’s processing only applies to Markdown and MDX content loaded using Starlight’s `docsLoader()`. This new option allows to extend this processing to other directories, which can be useful if you are rendering content from a custom content collection using the `<StarlightPage>` component and expect Starlight’s Markdown processing to be applied to that content as well.

docs/src/content/docs/reference/configuration.mdx

@@ -378,8 +378,8 @@ starlight({
 
 ### `markdown`
 
-**type:** `{ headingLinks?: boolean }`  
-**default:** `{ headingLinks: true }`
+**type:** `{ headingLinks?: boolean; processedDirs?: string[] }`  
+**default:** `{ headingLinks: true, processedDirs: [] }`
 
 Configure Starlight’s Markdown processing.
 
@@ -399,6 +399,28 @@ starlight({
 }),
 ```
 
+#### `processedDirs`
+
+**type:** `string[]`  
+**default:** `[]`
+
+Define additional directories where files should be processed by Starlight’s Markdown pipeline.
+By default, only Markdown and MDX content loaded using Starlight's [`docsLoader()`](/reference/configuration/#docsloader) is processed.
+Supports local directories relative to the root of your project, e.g. `'./src/data/comments/'`.
+
+Starlight’s processing includes support for [clickable heading anchor links](#headinglinks), [asides Markdown directive syntax](/guides/authoring-content/#asides), and RTL support for code blocks.
+This option can be useful if you are rendering content from a custom content collection in a [custom page](/guides/pages/#custom-pages) using the `<StarlightPage>` component and expect Starlight's Markdown processing to be applied to that content as well.
+
+```js
+starlight({
+	markdown: {
+		// Process Markdown files from the `reviews` content collection located in the
+		// `src/data/reviews/` directory.
+		processedDirs: ['./src/data/reviews/'],
+	},
+}),
+```
+
 ### `expressiveCode`
 
 **type:** `StarlightExpressiveCodeOptions | boolean`  

eslint.config.mjs

@@ -66,7 +66,12 @@ export default tseslint.config(
 			// or starting with `_`.
 			'@typescript-eslint/no-unused-vars': [
 				'error',
-				{ ignoreRestSiblings: true, destructuredArrayIgnorePattern: '^_', varsIgnorePattern: '^_' },
+				{
+					ignoreRestSiblings: true,
+					destructuredArrayIgnorePattern: '^_',
+					varsIgnorePattern: '^_',
+					argsIgnorePattern: '^_',
+				},
 			],
 			// Allow using `any` in rest parameter arrays, e.g. `(...args: any[]) => void`.
 			'@typescript-eslint/no-explicit-any': ['error', { ignoreRestArgs: true }],

packages/starlight/__e2e__/basics.test.ts

@@ -408,6 +408,17 @@ test.describe('components', () => {
 			await starlight.goto('/reviews/alice');
 			await expect(page.locator('.sl-anchor-link')).not.toBeAttached();
 		});
+
+		test('renders headings anchor links for entries not part of the `docs` collection matching the `markdown.processedDirs` option', async ({
+			getProdServer,
+			page,
+		}) => {
+			const starlight = await getProdServer();
+
+			// Content entry from the `comments` content collection
+			await starlight.goto('/comments/bob');
+			await expect(page.locator('.sl-anchor-link').first()).toBeAttached();
+		});
 	});
 
 	test.describe('asides', () => {
@@ -420,12 +431,22 @@ test.describe('components', () => {
 			// Individual Markdown page
 			await starlight.goto('/markdown-page');
 			await expect(page.locator('.starlight-aside')).not.toBeAttached();
-			await page.pause();
 
 			// Content entry from the `reviews` content collection
 			await starlight.goto('/reviews/alice');
 			await expect(page.locator('.starlight-aside')).not.toBeAttached();
 		});
+
+		test('renders Markdown asides for entries not part of the `docs` collection matching the `markdown.processedDirs` option', async ({
+			getProdServer,
+			page,
+		}) => {
+			const starlight = await getProdServer();
+
+			// Content entry from the `comments` content collection
+			await starlight.goto('/comments/bob');
+			await expect(page.locator('.starlight-aside')).toBeAttached();
+		});
 	});
 
 	test.describe('RTL support', () => {
@@ -443,6 +464,17 @@ test.describe('components', () => {
 			await starlight.goto('/reviews/alice');
 			await expect(page.locator('code[dir="auto"]')).not.toBeAttached();
 		});
+
+		test('adds RTL support to code and preformatted text elements for entries not part of the `docs` collection matching the `markdown.processedDirs` option', async ({
+			getProdServer,
+			page,
+		}) => {
+			const starlight = await getProdServer();
+
+			// Content entry from the `comments` content collection
+			await starlight.goto('/comments/bob');
+			await expect(page.locator('code[dir="auto"]').first()).toBeAttached();
+		});
 	});
 
 	test.describe('head propagation', () => {

packages/starlight/__e2e__/fixtures/basics/astro.config.mjs

@@ -7,6 +7,7 @@ export default defineConfig({
 		starlight({
 			title: 'Basics',
 			pagefind: false,
+			markdown: { processedDirs: ['./src/content/comments/'] },
 		}),
 	],
 });

packages/starlight/__e2e__/fixtures/basics/src/content.config.ts

@@ -10,4 +10,9 @@ export const collections = {
 		loader: glob({ base: './src/content/reviews', pattern: `**/[^_]*.{md,mdx}` }),
 		schema: z.object({ title: z.string() }),
 	}),
+	// A collection opted in to Starlight’s Markdown processing.
+	comments: defineCollection({
+		loader: glob({ base: './src/content/comments', pattern: `**/[^_]*.{md,mdx}` }),
+		schema: z.object({ title: z.string() }),
+	}),
 };

packages/starlight/__e2e__/fixtures/basics/src/content/comments/bob.mdx

@@ -0,0 +1,18 @@
+---
+title: Comment from Bob
+---
+
+# Comment from Bob
+
+This is a comment from Bob.
+
+## Description
+
+This content collection entry is not part of the Starlight `docs` collection.
+It is used to test that various remark/rehype plugins are transforming non-docs collection entries matching the `markdown.processedDirs` option.
+
+:::note
+This is a note using Starlight Markdown aside syntax.
+:::
+
+This is an `inline code` example.

packages/starlight/__e2e__/fixtures/basics/src/pages/comments/[...comment].astro

@@ -0,0 +1,21 @@
+---
+import { getEntry, render } from 'astro:content';
+
+/**
+ * This route is used to test that remark/rehype plugins are transofming non-docs collection
+ * entries matching the `markdown.processedDirs` option.
+ */
+
+export function getStaticPaths() {
+	return [{ params: { comment: 'bob' } }];
+}
+
+// @ts-expect-error - we don't generate types for this test fixture before type-checking the entire
+// project.
+const entry = await getEntry('comments', 'bob');
+if (!entry) throw new Error('Could not find Bob review entry.');
+
+const { Content } = await render(entry);
+---
+
+<Content />

packages/starlight/__e2e__/fixtures/basics/src/pages/reviews/[...review].astro

@@ -2,8 +2,8 @@
 import { getEntry, render } from 'astro:content';
 
 /**
- * This route is used to test that anchor links for headings are not generated for non-docs
- * collection entries.
+ * This route is used to test that remark/rehype plugins are not transforming non-docs collection
+ * entries.
  */
 
 export function getStaticPaths() {

packages/starlight/__tests__/basics/config-errors.test.ts

@@ -65,6 +65,7 @@ test('parses bare minimum valid config successfully', () => {
 		  "locales": undefined,
 		  "markdown": {
 		    "headingLinks": true,
+		    "processedDirs": [],
 		  },
 		  "pagefind": {
 		    "ranking": {