Module

debug.shortcode_sandbox

Shortcode/Directive Sandbox for isolated testing.

Test directives and shortcodes in isolation without building an entire site. Validates syntax, shows rendered output, and identifies errors before they appear in production builds.

Example usage:

sandbox = ShortcodeSandbox()
result = sandbox.render('''
```{note}
This is a test note.

''') print(result.html)

View source
3 Classes

Classes

RenderResult dataclass
Result of rendering a shortcode/directive.
1

Result of rendering a shortcode/directive.

Attributes

Name Type Description
input_content str
html str
success bool
directive_name str | None
errors list[str]
warnings list[str]
parse_time_ms float
render_time_ms float

Methods 1

format_summary
Format a summary of the render result.
0 str 
def format_summary(self) -> str

Format a summary of the render result.

Returns

str

ValidationResult dataclass
Result of syntax validation.
0

Result of syntax validation.

Attributes

Name Type Description
content str
valid bool
directive_name str | None
errors list[str]
suggestions list[str]
ShortcodeSandbox
Sandbox for testing shortcodes/directives in isolation. Provides: - Isolated rendering without sit…
13

Sandbox for testing shortcodes/directives in isolation.

Provides:

  • Isolated rendering without site context
  • Syntax validation before render
  • Error detection and suggestions
  • Batch testing from files
  • Interactive REPL mode
Inherits from DebugTool

Attributes

Name Type Description
name str
description str

Methods 7

run
Run sandbox testing.
3 DebugReport 
def run(self, content: str | None = None, file_path: Path | None = None, validate_only: bool = False, **kwargs: Any) -> DebugReport

Run sandbox testing.

Parameters 3
content str | None

Markdown content to test
file_path Path | None

Path to file containing content
validate_only bool

Only validate syntax, don't render **kwargs: Additional arguments
Returns

DebugReport —

DebugReport with findings

analyze
Perform analysis and return report. This is the abstract method required by De…
0 DebugReport 
def analyze(self) -> DebugReport

Perform analysis and return report.

This is the abstract method required by DebugTool. For parameterized analysis, use run() instead.

Returns

DebugReport

validate
Validate directive/shortcode syntax.
1 ValidationResult 
def validate(self, content: str) -> ValidationResult

Validate directive/shortcode syntax.

Parameters 1
content str

Markdown content with directive
Returns

ValidationResult —

ValidationResult with errors and suggestions

render
Render directive/shortcode content to HTML.
1 RenderResult 
def render(self, content: str) -> RenderResult

Render directive/shortcode content to HTML.

Parameters 1
content str

Markdown content with directive
Returns

RenderResult —

RenderResult with HTML and timing info

batch_test
Test multiple shortcodes in batch.
1 list[RenderResult] 
def batch_test(self, test_cases: list[dict[str, Any]]) -> list[RenderResult]

Test multiple shortcodes in batch.

Parameters 1
test_cases list[dict[str, Any]]

List of test cases with 'content' and optional 'expected'
Returns

list[RenderResult] —

List of RenderResults

list_directives
List all available directives with descriptions.
0 list[dict[str, str]] 
def list_directives(self) -> list[dict[str, str]]

List all available directives with descriptions.

Returns

list[dict[str, str]] —

List of directive info dicts

get_directive_help
Get detailed help for a specific directive.
1 str | None 
def get_directive_help(self, name: str) -> str | None

Get detailed help for a specific directive.

Parameters 1
name str

Directive name
Returns

str | None —

Help text or None if not found

Internal Methods 6
__init__
Initialize sandbox.
2 None 
def __init__(self, site: Any = None, mock_context: dict[str, Any] | None = None) -> None

Initialize sandbox.

Parameters 2
site Any

Optional site instance for full context (creates mock if None)
mock_context dict[str, Any] | None

Optional mock context for variable substitution
_create_default_context
Create default mock context for rendering.
0 dict[str, Any] 
def _create_default_context(self) -> dict[str, Any]

Create default mock context for rendering.

Returns

dict[str, Any]

_get_known_directives
Get set of known directive names.
0 frozenset[str] 
def _get_known_directives(self) -> frozenset[str]

Get set of known directive names.

Returns

frozenset[str]

_get_parser
Get or create markdown parser.
0 Any 
def _get_parser(self) -> Any

Get or create markdown parser.

Returns

Any

_find_similar_directives
Find directives with similar names (typo detection).
3 list[str] 
def _find_similar_directives(self, name: str, known: frozenset[str], max_distance: int = 2) -> list[str]

Find directives with similar names (typo detection).

Parameters 3
name str
known frozenset[str]
max_distance int
Returns

list[str]

_levenshtein_distance staticmethod
Calculate Levenshtein distance between two strings.
2 int 
def _levenshtein_distance(s1: str, s2: str) -> int

Calculate Levenshtein distance between two strings.

Parameters 2
s1 str
s2 str
Returns

int