Starlight components and misc

Components

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.

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.

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, but 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.

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 (for example, bash, shell, zsh). Titles are styled differently in this context.

For example:

See what it looks like?

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

Tabs

You can keep multiple tab groups in a page synchronized by using syncKey.

All tabs on a page with the same syncKey value will display the same active label. This is especially helpful when documenting programming languages. Note that the synching only persists on the page, not across pages.

Add an identical syncKey property to each <TabItem>.

<Tabs syncKey="constellations">
  <TabItem label="Orion">Bellatrix</TabItem>
  <TabItem label="Gemini">Pollux</TabItem>
</Tabs>

_Some exoplanets:_

<Tabs syncKey="constellations">
  <TabItem label="Orion">HD 34445 b</TabItem>
  <TabItem label="Gemini">Pollux b</TabItem>
</Tabs>

Bellatrix

Orion
Gemini

HD 34445 b

Misc

Style a single page with CSS

If there’s a style you need to apply to an entire page, to every instance of an element, you can do so in the frontmatter.

For example, the tables in the Sequence diagram style guide were behaving poorly. Text aligned itself to baseline which pushed the content in the last row outside the table’s bounds. Also, some code that needed to appear on a single line was breaking.

Instead of adding styles in each table in the page, the styles were applied to the page itself like so:

---
title: Sequence diagram style guide
head:
  - tag: style
    content: th, td {vertical-align:top !important; min-width:105px;}
---

Starlight can get a little testy when it comes to indentations. If you’re getting errors, copy the code block above and update it as needed.