Starlight — the docs theme's components & authoring surface

Starlight (v0.41.7 here) themes the gatOS docs site: sidebar, search, dark mode, and a set of built-in components you use inside .mdx pages. This skill is the component + frontmatter + syntax cheat sheet. For the framework underneath (MDX mechanics, content collections, config, build) see the astro skill; for the gatOS-specific writing style, the tutorials skill.

One import line covers every component:

import { Aside, Tabs, TabItem, Steps, Card, CardGrid, LinkCard, LinkButton, FileTree, Badge, Icon, Code } from '@astrojs/starlight/components';

Import only what a page uses. Components need .mdx (not .md) — asides are the one exception (their ::: Markdown shorthand works in both).

---

Frontmatter — the page's control panel

Validated at build time by docsSchema() (a wrong field name/type fails the build). Only title is required; always add an outcome-named description.

---
title: Point at parent                       # required — H1, browser tab, sidebar label, metadata
description: >-                               # one sentence — page subtitle + search/social snippet
  Aim a vessel's nose at its parent body with a computed Body→CCI quaternion, over /sim.
sidebar:
  order: 4                                    # position in its sidebar group; lower = higher. Omit → alphabetical
  label: Point at parent                      # shorter sidebar text (defaults to title)
  badge: { text: New, variant: tip }          # pill on the sidebar link; variant: note|tip|caution|danger|success|default
  hidden: false                               # true → keep the page but drop it from the autogenerated sidebar
tableOfContents:                              # default shows H2+H3; narrow or disable it
  minHeadingLevel: 2
  maxHeadingLevel: 3
# tableOfContents: false                      # hide the on-page TOC entirely
# template: doc                               # 'doc' (default) or 'splash' (wide, no sidebars — landing pages)
# prev: false   next: { link: /gatOS/guides/x/, label: Next }   # override the footer prev/next links
# draft: true                                 # visible in dev only; excluded from the build
---

Field notes:

• sidebar.order is how you slot a tutorial into the ladder — set it explicitly rather than trusting alphabetical order.
• badge.variant and the <Badge>/aside color words share the same palette: note(blue) tip(purple) caution(orange) danger(red) success(green) default(accent).
• hero, banner: { content }, head: [...], slug, editUrl, lastUpdated, pagefind: false exist too; index.mdx uses hero. Reach for them rarely.

---

Asides (callouts) — the tutorial's margin notes

Markdown shorthand — preferred, works in .md and .mdx, no import. Four types:

:::note
Default heads-up. Title defaults to "Note".
:::

:::tip[Shortcut: let the autopilot name it]
Custom title goes in the square brackets. Use for "you can skip the math" shortcuts.
:::

:::caution[Solver-phase latency]
Footguns: authority gate, time-warp, `controllable == 0`, a one-shot already fired.
:::

:::danger
Irreversible / destructive actions (rare in flight tutorials).
:::

• Custom title: :::tip[Your title]. Custom icon: :::note{icon="rocket"} (a built-in icon name). Combine: :::tip[Did you know?]{icon="heart"}.
• Asides can contain nested Markdown and fenced code blocks — keep a blank line before the closing :::.
• Component form (identical output, use inside JSX or when you want props): <Aside type="tip" title="…" icon="…">…</Aside> — type: note|tip|caution|danger.

---

Tabs — the dual-transport pattern (the key gatOS convention)

Show the same operation two ways (in-guest /sim vs host HTTP). Give every transport tab group the same syncKey so a reader picks once and the whole page — and future visits — follow:

<Tabs syncKey="transport">
  <TabItem label="/sim (in guest)">
    ```sh
    echo Prograde > /sim/vessels/active/ctl/attitude_mode
    ```
  </TabItem>
  <TabItem label="HTTP (host)">
    ```sh
    curl -X POST --data 'Prograde' \
      http://127.0.0.1:4242/v1/fs/vessels/active/ctl/attitude_mode
    ```
  </TabItem>
</Tabs>

• <TabItem label="…"> — label is required; add icon="…" for an icon beside it.
• syncKey synchronizes groups across the page and across pages — identical syncKey and identical labels per tab. Use syncKey="transport" for the /sim-vs-HTTP split, syncKey="lang" for Python/TS/shell.
• Keep tabs logically identical — same steps and values, differing only at the I/O edge.

---

Steps — numbered procedures

Wraps an ordered list into connected step markers. No props.

<Steps>

1. Read the vessel's position in CCI.
2. Negate it to get the aim direction.
3. Write the setpoint and exit.

</Steps>

Keep blank lines inside so the list parses. List items can hold paragraphs, code, and asides.

---

FileTree — show a folder layout

Renders a collapsible directory tree from a plain Markdown list. No props. Perfect for "here's the folder your scripts live in."

<FileTree>

- flight/
  - gatos_io.py       read & write /sim
  - gatos_frames.py   vectors + the Body→CCI quaternion
  - **point-at-parent.py**   the program we're building
  - ...

</FileTree>

Syntax rules:

• Nested list = subdirectory. Indent with two spaces per level.
• Trailing / marks a directory (flight/); without it the entry gets a file icon (extensions pick the icon).
• **name** highlights/emphasizes a file (the one you want the eye drawn to).
• Text after a filename is a comment (inline **bold**/_italic_ allowed).
• ... or … as a list item means "more files omitted here."
• Wrap names with spaces/underscores in backticks: `__init__.py`.

---

Cards & links — landing/next-step UI

<CardGrid>
  <Card title="Read telemetry" icon="document">Print a one-line orbit summary.</Card>
  <Card title="Schedule a burn" icon="rocket">Turn the pointing into a maneuver.</Card>
</CardGrid>

<LinkCard title="Point at parent" href="/gatOS/guides/vessel-control-point-at-parent/"
  description="The gentler first program this one builds on." />

<LinkButton href="/gatOS/guides/gatos-io/" variant="secondary" icon="right-arrow">Build the toolkit first</LinkButton>

• <Card title icon> — title required; icon optional (built-in icon name). Content is the children. <CardGrid> lays cards out responsively (add stagger for an offset grid on splash pages).
• <LinkCard title href description?> — a large clickable card; title + href required. Also takes any <a> attributes. Put one at the foot of a tutorial pointing to the next rung.
• <LinkButton href variant? icon? iconPlacement?> — a button-style link. variant: primary(default)|secondary|minimal; iconPlacement: start|end(default).
• Remember the /gatOS/ base in every href (see the astro skill) — the existing pages use /gatOS/guides/…/ with a trailing slash. Match that exactly.

---

Badge & Icon — inline accents

Status: <Badge text="Solver-phase" variant="caution" size="small" />
<Icon name="rocket" size="1.5rem" />

• <Badge text variant? size? class?> — text required; variant = the color palette above; size: small|medium|large. Great for tagging a heading or a term inline.
• <Icon name size? color? class?> — name is a built-in Starlight icon. Icon names are also what the icon= prop on Tabs/Card/LinkButton/asides accepts. Common ones: rocket, star, moon, document, information, warning, right-arrow, open-book, setting, puzzle, heart. The full set is the Starlight icons reference; if unsure, omit the icon rather than guess a bad name (an invalid icon name fails the build).

---

Code blocks — Expressive Code meta strings

Starlight renders fenced code blocks with Expressive Code: a language plus a meta string after the opening fence controls titles and highlighting. All of these go on the ```lang line:

```python title="point-at-parent.py"
# a filename caption renders above the block
```

```python {2,5-7}
# highlight line 2 and lines 5–7
```

```python "read_vec" /ctl\/\w+/
# highlight the text "read_vec" and anything matching the regex
```

```python ins="added this" del="removed this"
# green insertion / red deletion markers on those substrings
```

```diff lang="python"
- old = 1        # diff markers with real python syntax highlighting
+ new = 2
```

```sh title="run it" frame="none"
python3 point-at-parent.py Hunter    # frame="none" drops the terminal chrome
```

• title="…" → a file/tab caption (or use a // filename.js first-line comment). A sh/bash block auto-renders as a terminal frame; frame="none" disables it, frame="code" forces the editor frame.
• {n} / {a-b} highlight lines; "text" or /regex/ highlight substrings; ins=/del= mark added/removed substrings; a diff language + lang="…" gives real syntax highlighting under +/- gutters.
• For code assembled in JSX use the component: <Code code={str} lang="python" title="…" />.

---

Component-picking cheat sheet

I want to…	Use
a heads-up / caveat / footgun note	:::note / :::tip / :::caution / :::danger
show the same thing in-guest and over HTTP	<Tabs syncKey="transport"> + two <TabItem>
a numbered how-to	<Steps> around an ordered list
show a folder/file layout	<FileTree>
a named code file with highlights	fenced block + title= + {lines} / "text"
point to the next tutorial	<LinkCard> (big) or <LinkButton> (button)
a grid of "what's next" options	<CardGrid> of <Card>
tag a term/heading inline	<Badge>
an icon next to text	<Icon> (or icon= on Tabs/Card/aside)

Gotchas

• Components need .mdx. Only asides' ::: shorthand works in .md.
• Import + capitalize. Every component must be imported and written <LikeThis>.
• Blank lines around block components and inside <Steps>/<TabItem>/asides, or the Markdown stops parsing.
• href needs the /gatOS/ base and a trailing slash.
• Bad frontmatter field or icon name fails the build — that's the schema/Expressive-Code guard working, not a prose problem. Run pnpm build to catch it (see the astro skill).
• Props here match Starlight 0.41.7; a prop from a newer docs example may not exist. Check site/package.json if a component rejects a prop.