Authoring reference

This page is for us, not for customers

It is a live sample of the toolkit, so it has to be a real page to render — but it has no business shipping. Delete it, or set draft: true, before launch.

This page is .mdx. Components only work in .mdx; a .md file renders the import line as text. Asides, code blocks and Expressive Code work in both.

Asides

Four types, no more. The title in brackets is optional — without it you get the type name.

Not written yet

Use this for stubs. An unwritten page is not a hazard, and if every stub shouts amber then amber stops meaning anything.

Tip

For the shortcut someone would be pleased to learn.

Caution

For “this could go wrong” — reserve it, or it stops carrying weight.

Danger

For “this cannot be undone”. Rare.

:::note[Custom title]
Body.
:::

Steps

Wraps an ordered list. Use it for every Getting started page — it makes a procedure read as a procedure rather than as a list of sentences.

1. Open the project you want to rig.

2. Switch to Mocap and pick your camera.

   Steps can hold several paragraphs, code blocks and images — anything indented under the number stays in that step.

   koi doctor --camera

3. Check the character follows your head.

Tabs

Platform splits, without splitting the page. Give every tab set the same syncKey and choosing Windows once chooses it everywhere on the page.

Windows

Installs to %LOCALAPPDATA%\CoyKoi.

macOS

Installs to ~/Library/Application Support/CoyKoi.

iPhone

Nothing to install — it lives in the app.

Cards

Card

A block of highlighted content. Icons are optional.

Another

<CardGrid> lays them out; add stagger to offset the second column.

Link cardA card that is entirely a link. Good for 'next step' at the foot of a page.

Link button

Badges

Inline labels: New Pro only Deprecated

Also available in frontmatter, which is what puts “Internal” beside this page in the sidebar:

sidebar:
  badge: Internal

File tree

• Directorysrc

  • Directorycontent

    • Directorydocs

      • Directorystudio

        • index.md the introduction
        • Directorygetting-started/

          • …
    • Directoryshared/ written once, rendered into every app

      • …
• astro.config.mjs

Icons

Starlight’s set is listed in its own docs. The names are also what src/editions.ts uses for each app.

Code blocks

Expressive Code is on, so blocks do more than highlight. A title turns it into a framed file; a bash block with no title becomes a terminal frame.

src/editions.ts

export const EDITIONS = [
  { id: 'studio', label: 'Studio' },
  { id: 'prop', label: 'Prop' },
  { id: 'stream', label: 'Stream' },
  { id: 'legacy', label: 'Legacy' },
];

That block uses, in order: title= for the frame, {3} to mark a line, ins=/del= for added and removed lines, and "EDITION_IDS" to highlight every occurrence of a string.

Also available: showLineNumbers, startLineNumber=, collapse={4-10} to fold a range, and frame="none" to drop the chrome.

Diagrams

Two ways, for two jobs.

D2 for architecture — written as a fenced d2 block, rendered to SVG at build time. Works in .md as well as .mdx.

The diagram components for figurative explanation — the monoline set in src/components/diagram/.

The motif set lives in src/components/diagram/.

Varying a shared page by app

Only in src/content/shared/, and only in .mdx.

This paragraph renders under /studio/ and nowhere else. On this page it always shows, because this page is not shared.

<EditionOnly is={['prop', 'stream']}>
Shown under Prop and Stream, not Studio.
</EditionOnly>

Frontmatter

---
title: Install Studio          # required
description: One sentence.     # feeds search and social cards
sidebar:
  order: 2                     # lower floats higher; ties fall back to alphabetical
  label: Install               # shorter nav text than the title
  badge: New
  hidden: false                # keep the URL, drop it from the nav
draft: false                   # shows a notice; does NOT exclude from the build
layout: cards                  # this project's own: drops the sidebars, steps through sections
---

Things that will catch you out

1. Components need .mdx. A .md file prints the import line verbatim.

2. Shared pages should stay plain. Anything in src/content/shared/ is read by the Flutter app as raw, unprocessed markdown — components arrive there as literal tags. Keep them to markdown plus <EditionOnly>.

3. A new shared page needs a SHARED_NAV entry in src/editions.ts, or it builds and is reachable but never appears in a sidebar. App-specific pages under src/content/docs/<app>/ are picked up automatically.

4. sidebar.order does nothing on shared pages. They are ordered by their position in the SHARED_NAV array.

5. draft: true still ships. It adds a notice; it does not remove the page from a production build.

6. d2 needs the binary. No d2 on PATH and diagrams silently do not render — no error, just nothing.

7. Don’t run astro build while astro dev is up. They share the .astro/ content cache, and a build leaves the dev server serving stale pages until you restart it.