MDX `:::note` annotation not working with symlink

[LasseRosenow]

What version of starlight are you using?

0.36.0

What version of astro are you using?

5.14.4

What package manager are you using?

npm

What operating system are you using?

Linux

What browser are you using?

Chrome, Firefox

Describe the Bug

We need to use a symlink in content/docs that points to another folder higher up to make contribution of guides in our open source project (RIOT OS) more accessible. We need a symlink so that we can still have the remark and rehype plugins that are applied by starlight and only work with files from the content/docs folder.

We found a strange impact on rendering of :::note annotations with .mdx files when they come from the symlink. Even more strange is that this works for normal .md files. Only .mdx files are affected.

Background

Normally in .mdx files I can write this:

:::note
This is a note
:::

and it renders as this:

[!NOTE]
This is a note

But in a .mdx file that comes from a symlink this is ignored and the text is just printed normally without formatting.

Link to Minimal Reproducible Example

https://github.com/LasseRosenow/starlight-symlink-mdx-bug

Probably related:

#3332

Participation

• [ ] I am willing to submit a pull request for this issue.

[HiDeoo]

Thanks for the report :raised_hands:

What happens in this case, is that the aside syntax is handled in Starlight using Markdown plugins to parse, process, and transform the content. Such transformations happen at different time for Markdown files and MDX files, and they get different path values. Markdown files get the path in src/content/docs/ directory while MDX files get the path in docs/ (I guess they probably should be the same tho).

#3274 introduced a fix that prevents Starlight remark and rehype plugins from transforming content outside of src/content/docs/, which is why the aside syntax is not working in MDX files as they get a different path due to the symlink.

#3332 should fix this by allowing to configure the directories where Starlight remark and rehype plugins should apply the transformations. This way, you should be able to add docs/ to the list of directories to fix the issue.

[AnnsAnns]

Thank you for the (extremely) quick response. Glad to hear this being worked on, thank you 😄

[delucis]

Thanks for providing those workarounds @HiDeoo!

I’ll note that eventually we should aim to make sure this works automatically. We’ll need Astro to tell us the content collection root, so that our plugins can process things properly.