Starlight components and misc

Starlight offers a number of native components that we can use to style pages. The Components section in their docs outline how to use each one, though a few we commonly use are listed here.

• Asides
• Badges*
• Tabs

If a component is listed in their doc, but you get an error when trying to use it, we may need to upgrade Starlight.

Badges*

If you use badges to call out a particular REST API method, use the variant that most closely matches what appears for OpenAPIs in Swagger.

• GET - variant="note" (blue)
• POST - variant="success" (green)
• PUT - variant="caution" (yellow)
• DELETE - variant="danger" (red)

Code blocks

Code blocks in Markdown are fenced by three beginning and ending backticks (```). More information is found here. Information about how Starlight uses Expressive Code is also provided.

Hovering over a Starlight code block will display a copy button.

Note

As of November 29, 2023, this button will not appear when using the in-house ChunkedSnippet component. We’re tracking the issue in https://github.com/interledger/open-payments/issues/384.

Syntax highlighting

You can indicate the programming language to use if you want to use syntax highlighting. Astro uses Shiki, so check their documentation if you aren’t sure if your language is supported.

Block titles and frames

When we first deployed Starlight, it didn’t support adding titles to code blocks. This is why we have the in-house CodeBlock component.

Example code block with a title

This code block has a title! HJ made the component. Isn't she neat?

As of November 2023, Starlight now supports adding titles to code blocks; however, the title is styled to appear in a tab. Also, to use the Starlight title, you must specify a programming language.

We’ve chosen to keep our in-house CodeBlock component because we like the style more. However, you are free to use the Starlight defaults if they fit better with what you’re documenting.

Starlight default title style

I mean, at least it works by default now, right?

```js title="Starlight default title style"
I mean, at least it works by default now, right?
```;

By default, a Starlight code block will be rendered as a terminal window if a shell scripting language is used (e.g., bash, shell, zsh). Titles are styled differently in this context.

For example:

This uses bash

See what it looks like?

See the Frames and titles section in Starlight’s docs for more information.