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.

: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, 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).

: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.