Let remark plugins injected by Starlight plugins handle Markdown text and leaf directives

[HiDeoo]

Description

#1489 added a restoration process for unhandled generic Markdown directives. To do so, such directives are transformed back so they can render verbatim.

Altho, such process is done in the same remark plugin that handles asides. This means that any other remark plugin injected by Starlight plugins through Astro integrations won't be able to handle any of theses directives as they are transformed back to their original form before being processed by such plugins.

This PR addresses this issue by moving the restoration process to a new integration injecting a new remark plugin that will handle the restoration process and this integration is added after the ones potentially injected by Starlight plugins.

[changeset-bot]

🦋 Changeset detected

Latest commit: d65a34a

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	Patch

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

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	Jun 27, 2024 6:36pm

[delucis]

Thanks @HiDeoo! I think this looks good. Just to note, I think there can still be issues with remark plugins added by other integrations, e.g.

integrations: [starlight(), directiveIntegration()]

In this case the second integration would still add the remark plugin after Starlight restored things. If we also want to handle that case I guess instead of

integrations.push(starlightDirectivesRestorationIntegration());

https://github.com/HiDeoo/starlight/blob/493f973a9e587735402c8f8492e7c30e61076864/packages/starlight/index.ts#L79

we could push the restore integration to the end of the config.integrations array in theory. But I don’t know if that’s a good idea or not. (Not familiar with the issues this was causing.)

[HiDeoo]

Totally correct, I should have been more explicit about it in the PR description but that is the reason why I tried to always specify, even in the changeset, "remark plugins injected by Starlight plugins".

I was a bit afraid of the other approach and considering I am probably the only one hitting this issue now since asides are built-in in Starlight (which is pretty much since the beginning), I thought it would be better to start with this fix and see if we ever get another report about it.

[delucis]

Yes, that’s fine with me! Didn’t mean to suggest we should do that, just double check the scope of the fix was intentional. No need to “fix” something until we know it’s actually broken for someone. And in some ways this is less scary by making sure our logic is all scoped to the part of the process Starlight is responsible for.