Relax remark/rehype plugins usage

[HiDeoo]

Description

• Closes MDX :::note annotation not working with symlink #3470

This draft PR is a follow-up to #3274 which restricted the usage of Starlight remark and rehype plugins to only Markdown and MDX content loaded using Starlight's docsLoader(). As initially discussed and based on feedback, this PR relaxes that restriction using a new markdown.processedDirs (temporary name to be discussed) option that allows specifying additional directories where Markdown content should be processed by Starlight's remark and rehype plugins.

A few key points:

• As initially pointed out by Chris, checks are currently run by all Starlight remark and rehype plugins. If we're to potentially add more checks by allowing more directories, this PR felt like a good opportunity to refactor and limit the number of checks. Two ideas were envisaged:
  • Have some kind of "parent" plugin that runs the checks and then calls the other plugins if needed (this means 1 check for remark and 1 for rehype).
  • Have a remark plugin that runs before any other and using an approach similar to Astro saving a field in the vfile data, e.g. file.data.starlight.skip or something like that with a symbol, which plugins running after could check and decide if processing should continue or not (this means 1 check for both remark and rehype).
  • This PR explores the first option in a dedicated commit so we can easily revert/modify it if needed (personally not sure yet how I feel about it, need to take a step back).
• I went with directories paths relative to the project root instead of something like globs for this first iteration. I still wonder if we need the extra complexity/flexibility/cost of globs or just specifying directories is enough.

[changeset-bot]

🦋 Changeset detected

Latest commit: f484b10

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	f484b10
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/690b0c2e68d71a0008c84517
😎 Deploy Preview	https://deploy-preview-3332--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	reference/configuration.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[alvinometric]

markdown.includes ? Rather than processedDirs

[LasseRosenow]

Is this still being worked on? We depend on it for our documentation, because we would like to make our guides not so much hidden inside the starlight folder, to make contribution more accessible :)

Right now we are working around it using symlinks, but it also creates problems of their own, see: #3470

[HiDeoo]

Is this still being worked on?

Yes, this is not something we've been able to prioritize recently, but we do plan to get back to it and ship it in the next minor release hopefully.

[LasseRosenow]

That sounds amazing, thank you so much :)

[delucis]

This looks great and also nice to see the cleaned up code with the file path checks all centralised.

Left a few quick nots from stuff I spotted, but nothing major from me I don’t think.

• We’d discussed glob support, but I agree that the simple directories approach makes sense for now.

• I don’t have any particularly good ideas for the option naming. I tried to think of something that didn’t use the abbreviated “dirs”, but “directories” is long and “dir” is very common usage already, so I think it’s already quite good. It think the “processed” part of the name is nicely explicit too.

Thanks @HiDeoo!

[delucis]

Given we’re already abstracting these, do you think it might make sense to move the whole config behind an abstraction?

i.e. markdown: starlightMarkdownConfig(remarkRehypeOptions)

[HiDeoo]

Interesting, did not think of that. Just tried it locally and it definitely simplifies the code a bit in this file (packages/starlight/index.ts), I am not a big fan of the impact on tests.

For example, in some tests, we dynamically add plugins after Starlight's own plugins. With this change, this now means we need to first get the full markdown config from starlightMarkdownConfig(), then spread specific type of plugins and add our own:

const markdownConfig = starlightMarkdownConfig(
	await createRemarkRehypePluginTestOptions(starlightConfig)
);

const processor = await createMarkdownProcessor({
	...markdownConfig,
	remarkPlugins: [
		...markdownConfig.remarkPlugins,
		// The restoration plugin is run after the asides and any other plugin that may have been
		// injected by Starlight plugins.
		remarkDirectivesRestoration,
	],
});

We also have some specific tests that currently focus on a type of plugin and expect to not run with the other type, e.g. we have a test only running remark plugins with the ## Environment variables (astro:env) input to test the aside directive handling. In this case, we expect the output to be <h2 id="environment-variables-astroenv">Environment variables (astro:env)</h2> which is simple enough to assert. But if we run with the full markdown config, the rehype plugins will also run and add heading links.

We could of course adjust the tests to account for that, but it makes the assertions more complex and less focused on the specific feature being tested. We could also override the rehype plugins to an empty array in these specific tests, but that feels a bit less practical.

Another alternative, instead of only exporting starlightMarkdownConfig(), would be also to keep the current exports of starlightRemarkPlugins() and starlightRehypePlugins() for tests, but this feels like we're not fully committing and testing this abstraction.

I have kept the exploration of this suggestion in a stash if ever needed, but I'm not sure it's worth it given the above. What do you think?

[HiDeoo]

Thanks for the review 🙌

Updated the PR with the suggested changes, and commented on one of them but happy to discuss further!

I've also added a changeset for this new configuration option.