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.

[delucis]

Thanks again for the issue @serkangunes and apologies for not circling back sooner. Starlight now exposes an <Aside> component, so it is possible to configure Markdoc to render this with a custom tag.

Here is a small example project which sets this up: https://stackblitz.com/edit/github-upz7sj?file=markdoc.config.mjs

See markdoc.config.mjs for how the custom aside tag is configured and src/content/index.mdoc for a usage example.

// markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';

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

---
# src/content/index.mdoc 
title: Markdoc Asides example
template: splash
---

{% aside %}
This is a test aside
{% /aside %}

{% aside type="tip" %}
This is an aside with a specified type.
{% /aside %}

{% aside title="Custom Title" %}
This is an aside with a custom title.
{% /aside %}

In the future we might look to expose this Markdoc config as a helpful preset, but for now I think this should unlock anyone looking to use asides in their Markdoc documents.

[serkangunes]

@delucis Thanks for the update. This is cool.