Sphinx Directive#

The .. guidestar-demo:: directive embeds an interactive wireframe demo into any Sphinx-built documentation page.

Note

For a full list of configuration parameters, their types, defaults, and descriptions, see the Demo Options.

Basic syntax#

.. guidestar-demo:: _static/my-wireframe.html
   :steps: #btn@1500:click, #panel@1000:toggle-class=open
   :height: 400px

The first (required) argument is the path to the HTML file. It will be fetched at page load time via fetch(), so the file must be accessible from the browser. Typically this means placing it in your _static/ directory.

Directive options#

Option

Default

Description

:steps:

—

Comma-separated shorthand step strings. See Shorthand string format for the full syntax reference.

:steps-json:

—

Inline JSON array of step objects (alternative to :steps:).

:init-steps-json:

—

JSON array of steps executed silently before playback (or before a static render). Each step supports target, action / actions, value, noHighlight, chapter, caption, and captionOptions. The delay field is accepted but ignored. In static mode (no :steps:), the cursor is placed at the last targeted init step and the last caption persists. See Demo Options for details.

:cursor:

true

Show an animated cursor that moves to each target element (true / false). In static mode the cursor rests at the last init step’s target element when true.

:cursor-speed:

300

Duration in milliseconds for the cursor movement animation.

:repeat:

true

Loop the demo (true / false).

:auto-start:

true

Auto-start when visible (true / false).

:pause-on-interaction:

true

Pause on user click (true / false). Only active when :allow-user-interactions: true; ignored otherwise (the interaction blocker handles toggling in the default mode).

:step-range:

—

Restrict autoplay and loop to a slice of the step list, e.g. :step-range: 0-2 or :step-range: 0 2. Timeline dots outside the range are shown at reduced opacity but remain clickable. Omit to play all steps.

:allow-user-interactions:

false

When false (the default), a transparent glass pane covers the demo content so all clicks toggle play/pause instead of activating links or form controls in the underlying wireframe or live source. Set to true to allow full user interaction with the content (e.g. clicking buttons, filling forms); :pause-on-interaction: then resumes its role. For live URL sources, leave this at false — see Live URL.

:reload-on-restart:

false

Re-fetch htmlSrc on every restart instead of restoring the initial HTML snapshot (true / false). Useful for live URL sources where inline scripts add global event listeners on each execution cycle. Adds a network round-trip on restart. See Live URL for full details.

:css:

—

Path to an additional CSS file to include.

:js:

—

Path to an additional JS file to include.

:id:

auto

Explicit container id attribute.

:height:

—

Container height (e.g. 400px, 50vh).

:reduce-motion:

auto

Reduced-motion behaviour (auto / true / false). See Accessibility.

:viewport:

—

Fixed design width in CSS pixels (e.g. 1440). When set, the wireframe is rendered internally at that width and scaled uniformly to fit the demo container (scale mode). Omit to let the wireframe reflow responsively to the container width (responsive mode).

Set this when the wireframe was generated from a live URL at a specific desktop resolution — it ensures the content always matches the captured design at any container size.

Using from an external package#

Suppose your package mypackage ships its own wireframe HTML and wants to embed demos in its Sphinx documentation.

  1. Add guidestar as a docs dependency:

    # pyproject.toml
[project.optional-dependencies]
docs = ["sphinx-guidestar"]

  2. Enable the extension in conf.py:

    extensions = [
    'guidestar',
    # ... your other extensions
]

  3. Place your wireframe HTML in docs/_static/mypackage-wireframe.html.

  4. Use the directive anywhere in your RST:

    .. guidestar-demo:: _static/mypackage-wireframe.html
   :steps: #load-btn@1500:click, #sidebar@1000:add-class=visible
   :height: 500px

  5. If your wireframe needs domain-specific actions, register them in an additional JS file:

    // docs/_static/mypackage-demo-actions.js
Guidestar.registerAction('open-sidebar', function(step, el, root) {
    root.querySelector('.sidebar').classList.add('visible');
});

    Then include it via the :js: option:

    .. guidestar-demo:: _static/mypackage-wireframe.html
   :js: _static/mypackage-demo-actions.js
   :steps: #toolbar@1500:open-sidebar

Multiple instances#

You can place multiple .. guidestar-demo:: directives on the same page. Each gets its own independent container, playback state, and controls:

First demo
----------

.. guidestar-demo:: _static/demo-a.html
   :steps: #a1@1500:click, #a2@1000:toggle-class=on
   :height: 300px

Second demo
-----------

.. guidestar-demo:: _static/demo-b.html
   :steps: #b1@1500:click
   :height: 300px

They will not interfere with each other — each instance manages its own step index, timers, and pause state.

Adding captions#

Steps can include transcript-style captions that appear as a semi-transparent overlay at the top or bottom of the demo container.

Using the shorthand :steps: syntax, append |caption text to any step string. Use ^ or v to force top or bottom positioning:

.. guidestar-demo:: _static/my-wireframe.html
   :steps: #btn@1500:click|Click the button, #panel@1000:toggle-class=open|^Panel opens, pause@2000|vDone!
   :height: 400px

Using :steps-json: for full control, include caption and optionally captionOptions on each step object:

.. guidestar-demo:: _static/my-wireframe.html
   :steps-json: [
      {"target": "#btn", "action": "click", "delay": 1500,
       "caption": "Click the button"},
      {"target": "#panel", "action": "toggle-class", "value": "open",
       "delay": 1000, "caption": "Panel opens",
       "captionOptions": {"position": "top"}},
      {"action": "pause", "delay": 2000,
       "caption": "All done!", "captionOptions": {"position": "bottom"}}
      ]
   :height: 400px

Steps without a caption will hide any previously visible caption. See Demo Options for the full list of captionOptions fields and CSS custom properties for styling.