Custom types for asides

[essential-randomness]

What version of starlight are you using?

0.24.4

What is your idea?

As the title says, allow adding custom types for asides. This is possible in Docusaurus (which uses a similar syntax for asides) by using configuration options, but it's not possible in Starlight.

Looking at the code of the remark plugin, this should be as simple as adding an additional configuration options with a list of aside types and icons. My only doubt is how this would work with i18n, which I've never used with Starlight, though I don't think the other types are localized either.

Why is this feature necessary?

In our guides, we use different types of callout that are not matched by Starlight's defaults. For example, we differentiate between a "tip" and a "question". We also have "action" asides for extra actions the reader is supposed to take when following along an exercise.

Do you have examples of this feature in other projects?

Here's the feature's documentation in Docusaurus

Participation

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

[delucis]

Thanks for the idea @essential-randomness! I guess this is specifically about adding extra directives. Asides currently have a couple of components:

• Default label (“Tip”, “Note” etc.)
• Icon
• Colours: border colour, heading text colour, background colour

So I guess a feature like this would need that too and assumes people want customisation but not much customisation (because basically the asides would still have the same format).

The alternative might be a generic Astro integration which maps remark directives to whatever user-defined components you provide. Then that doesn’t need to be built into Starlight and gives more flexibility. Was chatting about that with @OliverSpeir the other day.

My only doubt is how this would work with i18n, which I've never used with Starlight, though I don't think the other types are localized either.

The other types all come with translations for their default labels, so presumably this should work the same somehow. Definitely a tricky aspect about designing an API to support this!

[pmc4]

Hi! I would like to link the asides (admonitions) of mkdocs-material to show how they look like.

I find very useful to have a huge variety when creating my notes in Markdown. At the end of the wepage it is also explained how to create a custom admonition. As you said, you only need the label, the icon and the colours.

I thought this answer could give an idea.

[OliverSpeir]

Yeah allowing custom components .astro via remark directive would be really cool, you could pass the locale into the component for i18n

Having the current remark component accept more props would be cool too like a background color and icon etc so you can customize on the fly as well

[essential-randomness]

For the default label, one could use the name of the aside type (e.g. "question" or "my-type"=>"my type"), unless the option is provided. Or you can default to any of the others, which is what Docusaurus did (defaulted to note IIRC, though I'd have to check again). Translations needed can be provided in the options and it can default to not translating it.

For colors, what docusaurus did was adding a class to the aside which was the name of the new type. This allows people to override styling with their own custom ones. I don't know what your custom styling for asides is like, but I assume any would be fine. "Customizing but not too much" is the idea here. I wouldn't want to define a new component from scratch.

The idea of custom directives is interesting, but for this specific issue only if I could still reuse Starlight's Aside somehow. I don't really want to create a new Aside component and have it clutter my components folder, or keep it up to date with how Starlights's look like. With that said, I do think it's an interesting idea, and I might consider helping according to how much work it is :P

[lorenzolewis]

I would personally much prefer just extending the current Astro component to allow further customization. The DX of complex markdown directives were always way over-complicated imo.

[essential-randomness]

This isn't really making markdown directives more complex on the side of the end developer though, it's just allowing different types of names to be used in directives that already exist. The complexity stays contained in the plugin itself, and this particular extension of it doesn't add much complexity on its own.

(edit: unless I misunderstood and you meant the other proposal, in which case oops, my bad :P)

[HiDeoo]

Adding @delucis's starlight-markdown-blocks plugin to the conversation which provides an easy but very powerful approach to extend Starlight’s Markdown asides syntax with custom block types.