Documentation Panel

🔄 Auto-generated mirror. Canonical source: docs/documentation-panel.md. Edit there — changes here are overwritten by CI.

Documentation panel

Nav: Quick start · Writing cases · Hierarchy · Tweaks · Theming · Documentation panel · Writing placard docs · Testing · CLI · AI agents · Configuration

Each component can carry prose documentation alongside its cases. Drop a <component>.placard.md file next to the component and Display Case renders it in a panel beside the showcase.

src/components/
  tweak-control.tsx
  tweak-control.case.tsx
  tweak-control.placard.md   ← rendered as the doc panel for "TweakControl"

There is nothing to wire up: the doc file is discovered automatically as the case file's sibling (same basename, .placard.md instead of .case.tsx). If the file is absent, the component simply has no doc panel — the manifest reports placardDoc: null for it.

What renders

The Markdown is rendered as full CommonMark + GFM (GitHub Flavored Markdown via markdown-to-jsx), so you get tables, task lists, strikethrough, and autolinks in addition to the core syntax:

# TweakControl

A single typed tweak input.

## Kinds

| Kind      | Use for                          |
| --------- | -------------------------------- |
| `text`    | free-form string values          |
| `boolean` | on/off toggles                   |
| `choice`  | selecting from fixed options     |

## Guidance

- Label every control from the tweak key.
- ~~Never~~ avoid free text where a `choice` would do.

The raw file is also served verbatim at /doc/<component> with a text/markdown content type, which is useful for machine readers.

Two intentional limits

• Raw HTML is disabled. Embedded <div>, <script>, <style>, etc. in a doc file are not rendered as markup — this prevents a doc from injecting into the showcase chrome. Stick to Markdown syntax.
• No syntax highlighting. Fenced code blocks render as plain styled <pre><code>. This is a deliberate non-goal for now; code is readable but not colorized.

Why .placard.md

The doc lives in prompt-friendly Markdown, next to the component. Authoring usage guidance once, beside the code, means it surfaces both in the showcase and to any tool that reads the file directly — see AI agents.

This page covers how the panel renders. For what to put in the file — the content that earns its place beside the types — see Writing placard docs.