Module

rendering.plugins.directives.terminal

Terminal recording embed directives for Bengal.

Provides directives for embedding terminal recordings:

  • Asciinema: Terminal session recordings with playback controls

Architecture:

AsciinemaDirective extends BengalDirective with asciinema.org
integration and fallback for users without JavaScript.

Security:

Recording IDs are validated via regex to prevent injection.
Noscript fallbacks provide accessible link to recording.

Accessibility:

Title is required for WCAG compliance. ARIA role="img" used
for semantic meaning. Recommend providing transcript for
complex recordings.

Related:

  • bengal/rendering/plugins/directives/base.py: BengalDirective
  • RFC: plan/active/rfc-media-embed-directives.md
View source
2 Classes

Classes

AsciinemaOptions dataclass
Options for Asciinema terminal recording embed.
0

Options for Asciinema terminal recording embed.

Inherits from DirectiveOptions

Attributes

Name Type Description
title str

Required - Accessible title for recording (ARIA label)
cols int

Terminal columns (default: 80)
rows int

Terminal rows (default: 24)
speed float

Playback speed multiplier (default: 1.0)
autoplay bool

Auto-start playback (default: false)
loop bool

Loop playback (default: false)
theme str

Color theme name (default: asciinema)
poster str

Preview frame - npt:MM:SS or data:text/plain,... (default: npt:0:0)
idle_time_limit float | None

Max idle time between frames in seconds
start_at str

Start playback at specific time (seconds or MM:SS)
css_class str

Additional CSS classes
_field_aliases ClassVar[dict[str, str]]
AsciinemaDirective
Asciinema terminal recording embed directive. Embeds asciinema.org terminal recordings with custom…
3

Asciinema terminal recording embed directive.

Embeds asciinema.org terminal recordings with customizable playback options. Uses official script-based embed with noscript fallback.

Syntax:

:::{asciinema} recording_id
:title: Installation Demo
:cols: 80
:rows: 24
:speed: 1.5
:autoplay: true
:::

Options:

:title: (required) Accessible title for recording
:cols: Terminal columns (default: 80)
:rows: Terminal rows (default: 24)
:speed: Playback speed multiplier (default: 1.0)
:autoplay: Auto-start playback (default: false)
:loop: Loop playback (default: false)
:theme: Color theme name (default: asciinema)
:poster: Preview frame - npt:MM:SS (default: npt:0:0)
:idle-time-limit: Max idle time between frames in seconds
:start-at: Start playback at specific time
:class: Additional CSS classes

Output:

<figure class="asciinema-embed" role="img" aria-label="...">
  <script id="asciicast-..." src="https://asciinema.org/a/....js"
          async data-cols="80" data-rows="24" ...></script>
  <noscript>
    <a href="https://asciinema.org/a/...">View recording: ...</a>
  </noscript>
</figure>

Security:

  • Recording ID validated (numeric only)
  • All data attributes properly escaped

Accessibility:

  • ARIA role="img" with aria-label
  • Noscript fallback with link
  • Recommend providing transcript for complex recordings
Inherits from BengalDirective

Attributes

Name Type Description
NAMES ClassVar[list[str]]
TOKEN_TYPE ClassVar[str]
OPTIONS_CLASS ClassVar[type[DirectiveOptions]]
DIRECTIVE_NAMES ClassVar[list[str]]
ID_PATTERN ClassVar[re.Pattern[str]]

Methods 3

validate_source
Validate Asciinema recording ID (numeric only).
1 str | None 
def validate_source(self, recording_id: str) -> str | None

Validate Asciinema recording ID (numeric only).

Parameters 1
recording_id str
Returns

str | None

parse_directive
Build Asciinema embed token.
5 DirectiveToken 
def parse_directive(self, title: str, options: AsciinemaOptions, content: str, children: list[Any], state: Any) -> DirectiveToken

Build Asciinema embed token.

Parameters 5
title str
options AsciinemaOptions
content str
children list[Any]
state Any
Returns

DirectiveToken

render
Render Asciinema embed to HTML.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render Asciinema embed to HTML.

Parameters 2
renderer Any
text str
Returns

str