Module

rendering.plugins.directives.embed

Developer tool embed directives for Bengal.

Provides directives for embedding code playgrounds and developer tools:

  • GitHub Gists
  • CodePen
  • CodeSandbox
  • StackBlitz

Architecture:

All embed directives extend BengalDirective with type-specific validation
and rendering for their respective services.

Security:

All IDs/URLs are validated via regex patterns to prevent XSS and injection.
Script-based embeds (Gist) include noscript fallbacks.

Accessibility:

Title is required for iframe-based embeds to meet WCAG 2.1 AA requirements.

Related:

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

Classes

GistOptions dataclass
Options for GitHub Gist embed.
0

Options for GitHub Gist embed.

Inherits from DirectiveOptions

Attributes

Name Type Description
file str

Specific file from gist to display
css_class str

Additional CSS classes
_field_aliases ClassVar[dict[str, str]]
GistDirective
GitHub Gist embed directive. Embeds GitHub Gists using the official script embed method. Includes …
3

GitHub Gist embed directive.

Embeds GitHub Gists using the official script embed method. Includes noscript fallback with link to gist.

Syntax:

:::{gist} username/gist_id
:file: example.py
:::

Options:

:file: Specific file from gist to display
:class: Additional CSS classes

Output:

<div class="gist-embed">
  <script src="https://gist.github.com/username/gist_id.js?file=example.py"></script>
  <noscript><p>View gist: <a href="...">username/gist_id</a></p></noscript>
</div>

Security:

  • Username validated (alphanumeric, underscore, hyphen)
  • Gist ID validated (32 hex characters)
  • File parameter escaped for URL safety
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 gist reference (username/gist_id).
1 str | None 
def validate_source(self, gist_ref: str) -> str | None

Validate gist reference (username/gist_id).

Parameters 1
gist_ref str
Returns

str | None

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

Build gist embed token.

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

DirectiveToken

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

Render gist embed to HTML.

Parameters 2
renderer Any
text str
Returns

str

CodePenOptions dataclass
Options for CodePen embed.
0

Options for CodePen embed.

Inherits from DirectiveOptions

Attributes

Name Type Description
title str

Required - Accessible title for iframe
default_tab str

Tab to show - html, css, js, result (default: result)
height int

Height in pixels (default: 300)
theme str

Color theme - light, dark, or theme ID (default: dark)
editable bool

Allow editing (default: false)
preview bool

Show preview on load (default: true)
css_class str

Additional CSS classes
_field_aliases ClassVar[dict[str, str]]
_allowed_values ClassVar[dict[str, list[str]]]
CodePenDirective
CodePen embed directive. Embeds CodePen pens using iframe with customizable display options. Synt…
4

CodePen embed directive.

Embeds CodePen pens using iframe with customizable display options.

Syntax:

:::{codepen} username/pen/pen_id
:title: Interactive Example
:default-tab: result
:height: 400
:::

Options:

:title: (required) Accessible title for iframe
:default-tab: Tab to show - html, css, js, result (default: result)
:height: Height in pixels (default: 300)
:theme: Color theme - light, dark (default: dark)
:editable: Allow editing (default: false)
:preview: Show preview on load (default: true)
:class: Additional CSS classes

Security:

  • Username validated (alphanumeric, underscore, hyphen)
  • Pen ID validated (alphanumeric, underscore, hyphen)
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 CodePen reference.
1 str | None 
def validate_source(self, pen_ref: str) -> str | None

Validate CodePen reference.

Parameters 1
pen_ref str
Returns

str | None

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

Build CodePen embed token.

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

DirectiveToken

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

Render CodePen embed to HTML.

Parameters 2
renderer Any
text str
Returns

str

Internal Methods 1
_parse_pen_ref
Parse pen reference into (username, pen_id).
1 tuple[str, str] 
def _parse_pen_ref(self, pen_ref: str) -> tuple[str, str]

Parse pen reference into (username, pen_id).

Parameters 1
pen_ref str
Returns

tuple[str, str]

CodeSandboxOptions dataclass
Options for CodeSandbox embed.
0

Options for CodeSandbox embed.

Inherits from DirectiveOptions

Attributes

Name Type Description
title str

Required - Accessible title for iframe
module str

File to show initially
view str

Display mode - editor, preview, split (default: split)
height int

Height in pixels (default: 500)
fontsize int

Editor font size (default: 14)
hidenavigation bool

Hide file navigation (default: false)
theme str

Color theme - light, dark (default: dark)
css_class str

Additional CSS classes
_field_aliases ClassVar[dict[str, str]]
_allowed_values ClassVar[dict[str, list[str]]]
CodeSandboxDirective
CodeSandbox embed directive. Embeds CodeSandbox projects using iframe with customizable display op…
3

CodeSandbox embed directive.

Embeds CodeSandbox projects using iframe with customizable display options.

Syntax:

:::{codesandbox} sandbox_id
:title: React Example
:module: /src/App.js
:view: preview
:::

Options:

:title: (required) Accessible title for iframe
:module: File to show initially
:view: Display mode - editor, preview, split (default: split)
:height: Height in pixels (default: 500)
:fontsize: Editor font size (default: 14)
:hidenavigation: Hide file navigation (default: false)
:theme: Color theme - light, dark (default: dark)
:class: Additional CSS classes

Security:

  • Sandbox ID validated (alphanumeric, 5+ characters)
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 CodeSandbox ID.
1 str | None 
def validate_source(self, sandbox_id: str) -> str | None

Validate CodeSandbox ID.

Parameters 1
sandbox_id str
Returns

str | None

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

Build CodeSandbox embed token.

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

DirectiveToken

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

Render CodeSandbox embed to HTML.

Parameters 2
renderer Any
text str
Returns

str

StackBlitzOptions dataclass
Options for StackBlitz embed.
0

Options for StackBlitz embed.

Inherits from DirectiveOptions

Attributes

Name Type Description
title str

Required - Accessible title for iframe
file str

File to show initially
view str

Display mode - editor, preview, both (default: both)
height int

Height in pixels (default: 500)
hidenavigation bool

Hide file navigation (default: false)
hidedevtools bool

Hide dev tools panel (default: false)
css_class str

Additional CSS classes
_field_aliases ClassVar[dict[str, str]]
_allowed_values ClassVar[dict[str, list[str]]]
StackBlitzDirective
StackBlitz embed directive. Embeds StackBlitz projects using iframe with customizable display opti…
3

StackBlitz embed directive.

Embeds StackBlitz projects using iframe with customizable display options.

Syntax:

:::{stackblitz} project_id
:title: Angular Demo
:file: src/app.component.ts
:view: preview
:::

Options:

:title: (required) Accessible title for iframe
:file: File to show initially
:view: Display mode - editor, preview, both (default: both)
:height: Height in pixels (default: 500)
:hidenavigation: Hide file navigation (default: false)
:hidedevtools: Hide dev tools panel (default: false)
:class: Additional CSS classes

Security:

  • Project ID validated (alphanumeric, underscore, hyphen)
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 StackBlitz project ID.
1 str | None 
def validate_source(self, project_id: str) -> str | None

Validate StackBlitz project ID.

Parameters 1
project_id str
Returns

str | None

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

Build StackBlitz embed token.

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

DirectiveToken

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

Render StackBlitz embed to HTML.

Parameters 2
renderer Any
text str
Returns

str