Fix rendering issue for text with unhandled generic Markdown directives

[HiDeoo]

What kind of changes does this PR include?

• Changes to Starlight code

Description

This PR is a follow-up to this Discord discussion.

The remark-directive plugin used to handle asides based on generic directives is responsible of parsing 3 different types of directives:

• text directives
• leaf directives
• container directives

Starlight only uses the last type but all types are parsed by the plugin. This means that content that may accidentally contain a directive of another type will be parsed as such and may lead to unexpected results. For example:

AWS re:Invent is a learning conference hosted by AWS.

The above sentence will be rendered as:

This PR fixes the issue by transforming the unhandled directive so that they render verbatim.

Note: this relies on mdast-util-to-markdown so that we can pass down to it the official directiveToMarkdown extension and automatically get the correct rendering for the directive including any attributes.

[changeset-bot]

🦋 Changeset detected

Latest commit: 814f0a3

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	Feb 12, 2024 3:05pm

[delucis]

Thanks for the quick diagnosis and fix @HiDeoo!

Left a note, but this looks good to me 🚀

[delucis]

Noting a subtle difference here in the transformation back to text where the attribute value becomes wrapped in ". It should be extremely rare that this is an issue though, as it only applies in a relatively complex string that is a correctly formed directive, so I guess that’s fine?

Suggested change

	`This is a:test of a sentence with a text:name[content]{key=val} directive.`
	);
	expect(res.code).toMatchInlineSnapshot(`
	"<p>This is a:test
	of a sentence with a text:name[content]{key="val"}
	directive.</p>"
	`);
	`This is a:test of a sentence with a text:name[content]{key=val} directive.`
	);
	expect(res.code).toMatchInlineSnapshot(`
	"<p>This is a:test
	of a sentence with a text:name[content]{key="val"}
	directive.</p>"
	`);

[HiDeoo]

Excellent catch, I totally missed that.

After a bit of digging, I found that mdast-util-directive respects options.quote altho in our case, this would not be enough to fix the issue.

I think the current approach is a good enough solution for now but if we ever hit the rare case you mentioned where we cannot restore the node to its exact original content including the quotes, we would need to revisit this. I think the 2 options would be to either:

• Only restore the node if it's a directive with no attributes and document/emit a warning when encountering a case where we cannot restore (this seems to be the Docusaurus approach)
• Find another way to properly restore the node (which I think would mean to have a copy of the AST before the directive was transformed)

Are you still okay with this approach?

• If no, I can work a refactor based on the solution we would choose
• If yes, I can merge this PR as it contains no doc changes in its current state

[delucis]

Yes, 100% approve — we can merge and release this as is.

If we run into this rare issue, we could also look into an alternative to remark-directive that only provides the container directive and not also text/lead directives.