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.