Aside markdown components are not working in markdoc

[serkangunes]

What version of starlight are you using?

0.11.1

What version of astro are you using?

3.2.3

What package manager are you using?

npm

What operating system are you using?

Mac

What browser are you using?

Chrome

Describe the Bug

Aside components rendered with ::: blocks are not working in markdoc files.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-pce8ue?file=src%2Fcontent%2Fdocs%2Findex.mdoc

Participation

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

[HiDeoo]

I am not a Markdoc user so I may be wrong, but I think this is currently the expected behavior.

The aside mechanism in Starlight is based on a remark plugin and as far as I know, remark is incompatible with Markdoc's transform pipeline.

If I were to imagine a potential solution, I think Markdoc's users would need to edit their markdoc.config.mjs (this could be properly documented if we come up with a solution) to define a new tag using a new potential <Aside/> component that could be exported by Starlight, e.g.

import { defineMarkdocConfig, component } from "@astrojs/markdoc/config";

export default defineMarkdocConfig({
  tags: {
    aside: {
      render: component('@astrojs/starlight/markdoc', 'Aside'),
      attributes: {
        type: { type: String, required: true, matches: ['note', 'tip', 'caution', 'danger'], },
        title: { type: String, required: false },
      },
    },
  },
});

If this was a valid setup, at this point users should now be able to use:

## Test

{% aside type="tip" %}

Hello from a tip aside!

{% /aside %}

Not sure if this is the best solution, but I think it could work but having the opinion of someone more familiar with Markdoc would be great.

[serkangunes]

I think that sounds like a great workaround for Markdoc users.

[delucis]

Yes, I can confirm this is expected as we’re using remark to extend Markdown and MDX syntax, an option not available in Markdoc.

We haven’t invested much in our Markdoc support yet, but I think in the future the aim would be to have a @astrojs/starlight-markdoc package that provides config for asides and all of Starlight’s other built-in components. @bholmesdev did some early exploration and shared notes in a thread on Discord.