Demos#

Demos turn Markdown code fences into live reference material. Use them when readers need to see a rendered result next to the source that produced it.

Rocket has two live demo frames:

• js demo creates a JavaScript Demo for browser-rendered component examples, interaction states, and small behavior samples.
• js request-demo creates a Request Demo for same-site GET responses, including request-time JavaScript Pages, JSON routes, generated SVG, and HTML endpoints.

Use a plain Code Block when the reader only needs source text.

Choose the frame#

Start with the output readers need to inspect, then choose the smallest frame that shows it.

JavaScript Demos#

A JavaScript Demo renders browser output from a named function export. It is the right frame for small live examples where the preview and the source code should stay together.

Basic authoring#

```js demo
import { html } from 'lit';

export const simpleButton = () => html`<button type="button">Click me</button>`;
```

Rocket renders the demo inside <rocket-js-demo> and displays the source code:

import { html } from 'lit';

export const simpleButton = () => html`<button type="button">Click me</button>`;

Every export in a js demo block becomes one demo. The export name also becomes part of the generated Standalone Demo URL.

Source labels#

Add label="..." when the displayed demo source should show a Code Block Label:

```js demo label="components/simple-button.js"
export const simpleButton = () => html`<button type="button">Click me</button>`;
```

The label belongs to the displayed source code. JavaScript Demo frames do not show a separate demo title by default.

Shared setup#

All demos on a Markdown Page are bundled into that Page's browser module. Put shared imports or setup code in js client when several demos need the same values:

```js client
import { html } from 'lit';
```

```js demo
export const primaryButton = () => html`<button type="button">Primary</button>`;
```

```js demo
export const secondaryButton = () => html`<button type="button">Secondary</button>`;
```

The demo function receives an options object. wrapperRef points at the JavaScript Demo element:

```js demo
export const measuredDemo = ({ wrapperRef }) => {
  wrapperRef.dataset.ready = 'true';
  return html`<p>Ready</p>`;
};
```

Component Pages#

Use demos on component Pages when readers need to compare live states with source code:

```js client
import { html } from 'lit';
```

```js demo
export const primaryAction = () => html` <acme-button href="/setup">Read setup</acme-button> `;
```

For components rendered inside demos, use a Loading Strategy that defines the element in the browser, such as client or hydrate:*. Server-only components are best shown directly in Markdown when their rendered HTML is the complete experience.

Standalone Demo URLs#

Every named JavaScript Demo export also gets a generated Standalone Demo URL:

<page path>/_demo/<demo export name>/

For this Page, Rocket generates:

/reference/demos/_demo/simpleButton/

Standalone Demo URLs are public, stable child paths. They require the trailing slash. Query-string forms such as ?standaloneDemo=simpleButton are not the public URL contract.

Avoid configuring Pages under a Page's reserved _demo segment unless you are intentionally checking for a collision.

Request Demos#

Use a Request Demo when the thing to inspect is a same-site request and response. The frame displays GET plus the authored request path, renders the response in a lazy iframe, keeps the source collapsed behind Source, and keeps controls for opening and copying the request path in the Source row.

```js request-demo url="/request-time-javascript-pages/demo/build-info.json?source=reference" label="docs/pages/guides/requestTimeBuildInfo.rocket.js" height=240
export const config = {
  path: '/request-time-javascript-pages/demo/build-info.json',
  render: 'server',
};

export default function content() {
  return {
    renderedAt: new Date().toISOString(),
    runtime: 'server',
  };
}
```

export const config = {
  path: '/request-time-javascript-pages/demo/build-info.json',
  render: 'server',
};

export default function content() {
  return {
    renderedAt: new Date().toISOString(),
    runtime: 'server',
  };
}

Request metadata#

Hashes, relative paths, protocol-relative URLs, and external URLs are rejected. Rocket does not validate that the target exists in the Page registry, so Request Demos can point at adapter routes, intentional 404 examples, or future routes.

Request Demo source is visible Markdown content only. Rocket does not execute it, extract it as js server or js client setup, bundle it as browser demo code, parse it as a JavaScript Demo, or validate it as a Page module.

Tips#

• Use demos for rendered examples, not long tutorials.
• Keep data small and local; demos run in the browser.
• Use Request Demos for request-time responses instead of hand-written iframe figures.
• Prefer Registered Components for reusable component files.
• Remember that custom element tags used in the parent Markdown content still need Page ownership through components or js client.