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 💡

[delucis]

<FileTree>

The Astro and Starlight docs both use a file tree component for rendering directory structures. For example, in Starlight’s “Sidebar” guide:

We already have a PR for adding this component to Starlight here: #1308

[bdenham]

I implemented a simpler, more compact version for my own usage, so I’m keen to see a native version implemented. That will be one less custom component I need to worry about!

[ematipico]

Very much needed!

[HiDeoo]

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

[delucis]

<Aside>

Starlight supports notes, tips, and other asides via a custom Markdown syntax:

:::tip
This is a tip
:::

In some contexts it could be helpful to have access to a .astro component version of this (e.g. to configure Markdoc or when using a custom page as will soon be possible via #1175)

[delucis]

Update on this one: available in Starlight v0.19!

[delucis]

<Badge>

Starlight already includes the ability to add badges to sidebar items. For example, in the current Starlight docs sidebar:

Would it be useful for people to be able to use this more freely inside content?

[HiDeoo]

Definitely one of the component I have duplicated the most in plugins: starlight-obsidian - starlight-blog

[kevinzunigacuellar]

I would like to champion this one, if possible 🥇

[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?

[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

[delucis]

<Steps>

Nextra and Vocs both include a <Steps> component for rendering a more in-your-face numbered list of steps.

Would that be something people would find helpful in their Starlight sites?

[sarah11918]

I am in favour of this one! We are constantly finding that we need to fiddle with indentation to have code and instructions inside numbered steps. We are constantly getting it wrong, then having other Docs PRs to clean it up.

We'd still have to do that inside a component, BUT I feel like it would be "a thing" and easier to document and make sure people get right all the time.

[bdenham]

This is one that I implemented on my own as an Astro component. Would be nice to see it natively implemented. Again, one less custom component required.

[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!

[Vrandus]

<Code>

An expressive-code component that can be used to wrap additional functionality above/below the code block within markdown while maintaining a unified experience with expressive-code's look and feel.

What could this enable?

• atomically build custom UI components using <Code>
• Easier implementation of two panel docs (left side content, right side code blocks)
• Ability to build language selector above code blocks
• For HTML code blocks, ability to render the html above the code block
• For GQL code blocks, ability to add a button below a code block to "run in playground"

Examples

• flex-box with code blocks: https://graphql.org/learn/queries/#using-variables-inside-fragments
• two panel design: https://shopify.dev/docs/api/admin-graphql/2024-01/mutations/marketLocalizationsRegister
• lang selector: https://stripe.com/docs/payments/accept-a-payment?platform=web&ui=checkout&lang=ruby#set-up-stripe
• HTML rendered above code blocks: https://mui.com/material-ui/react-button-group/#basic-button-group

[delucis]

We have great news for you! This is available as of v0.17 of Starlight: https://starlight.astro.build/guides/components/#code

[Faf4a]

<Details>

A details component, would be enough even if it's just some CSS from starlight's side.

I know this is already customizable with the usage of CSS but the current default component looks rather simple and doesn't match starlight's style.

Discord Discussion (everything below)

Examples

• https://docusaurus.io/docs/markdown-features#details

[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/

[stereobooster]

<kbd>

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

Example:

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

Cmd + F