Add more built-in components to Starlight

[delucis]

We have several components we built specifically for Astro’s Docs or ideas for components that we could add that would likely be generally helpful to Starlight users as they meet common documentation needs. This discussion is a place to share these ideas and give feedback.

How to use this discussion

• Upvote components that would be useful to you 🗳️
• Add additional thoughts as replies to the comment for the relevant component 💬
• Add an idea for a different component as a separate comment 💡

[HiDeoo]

Update: the <FileTree> component is available in Starlight v0.21 🎉

[delucis]

Update on this one: the <Aside> component is available in Starlight v0.19!

[delucis]

Thanks to @kevinzunigacuellar in #1530 the <Badge> component is available in Starlight v0.24 and higher!

[delucis]

<Button> (call to action)

Starlight’s hero component includes call-to-action style buttons:

Would it be useful to be able to use these in content?

[vvs-basanth]

Would it be possible to introduce a feature that allows us to customize the opacity of buttons when hovered over? This enhancement would enable us to apply specific styling properties, providing greater control over the visual feedback when users interact with buttons.

This addition would be highly beneficial for achieving a more tailored user experience.

[delucis]

<MultipleChoice>

Astro’s “Build a Blog” tutorial features multiple choice quizzes used for interactive tests of a user’s knowledge:

The authoring experience is quite nice on these:

<MultipleChoice>
  <Option>
    web browser
  </Option>
  <Option>
    Terminal
  </Option>
  <Option isCorrect>
    VS Code
  </Option>
</MultipleChoice>

Maybe people are interested in getting access to this as part of Starlight?

[lschierer]

more generically, support for Astro's HML Forms

[HiDeoo]

Update: the <Steps> component is available in Starlight v0.21 🚀

[santiemanuel]

<ImageComponent>

An image component with the ability to expand on click. Some images we use in Starlight are dense in information and those are only good for desktop users. Having the ability to zoom in an image would help mobile users to read the info.

[bdenham]

Yes, please! This is a big one for me. I try to include at least one diagram for every topic and it can be really hard to design it in a way that the callout text and graphics fit within the ~720px width of the content area for a page—while remaining readable!

In addition, I would also like to see an option for entering a caption that would appear consistently below the image.

I’d also like to see the same thing for a <VideoComponent />.

[libreom]

I need this for my doc site also thanks

[HiDeoo]

Not exactly a component as discussed here, but as a potential alternative, I made a Starlight plugin adding zoom capabilities to documentation images in case this might be useful to someone.

[bdenham]

@HiDeoo, I just went through your docs for the plugin. It’s perfect! The implementation and decisions you made for its design and default feature set are all spot on for my needs. Extremely well done. You made my week! Bravo!

[delucis]

We have great news for you! A <Code> component is available as of v0.17 of Starlight

[HiDeoo]

<details> elements are now styled by default since Starlight 0.23 🎉

[Darkflame72]

<ListCard> and <SplitCard>

Add the ListCard and SplitCard Cards that are used on the Astro Docs.

These provide more options with cards and styles for how they are used. List cards are often used to link to various parts of the docs and the Split card can be used for installation details or other important information.

[at-the-vr]

I mean Cards and Link Cards pretty much do the thing that your looking for, just the markup and css is left for user to manage

[Darkflame72]

They are similar but I can very much see use cases for these specific cards especially with a collection of links rather than a big block link.

[Darkflame72]

<Math>

Add a block to render MathJax this would be similar to the opt in functionality in VitePress. This is especially useful for any documentation around Machine Learning/Artifical Intelligence, Computer Graphics, Computer Vision and more where equations should be rendered near the code

[HiDeoo]

Just like VitePress uses markdown-it-mathjax3 to enable these features, Starlight is built on top of Astro which supports adding third-party Markdown plugins for Markdown and MDX.

In this specific case, this would be remark-math and rehype-mathjax.

You can find more informations with a small example and links to more example in this post. The entire conversation (and the last message) also contains various information about styling such expressions which you might find useful.

[Darkflame72]

It might be worth documenting this on the starlight docs as it may not be immediatly obvious (at least wasn't too me).

[torn4dom4n]

I think we need a plugin more than a built-in component. BTW, I'm using KaTeX to render LaTeX in starlight. You can find it here.

[stereobooster]

Here is how to configure math support in Starlight https://astro-digital-garden.stereobooster.com/recipes/math-support-in-markdown/

[delucis]

Here's another example of a Starlight project that can render MathJax syntax: https://starlight-examples.netlify.app/examples/mathjax/

[stereobooster]

<kbd>

Not exactly an Astro component, but rather CSS for HTML tag (kbd = keyboard)

Example:

<kbd>Cmd</kbd> + <kbd>F</kbd>

Cmd + F

[at-the-vr]

Decided to spin up a quick starlight site for this one https://htkbd.vercel.app/ for anyone interested