Module

rendering.plugins.directives.include

Include directive for Mistune.

Allows including markdown files directly in content.

Syntax:

```{include} path/to/file.md
```

Or with options:

```{include} path/to/file.md
:start-line: 5
:end-line: 20
```

Paths are resolved relative to the site root or the current page's directory.

Robustness:

  • Maximum include depth of 10 to prevent stack overflow
  • Cycle detection to prevent infinite loops (a.md → b.md → a.md)
  • File size limits to prevent memory exhaustion (10MB default)
  • Symlink rejection to prevent path traversal attacks
View source
1 Class 1 Function

Classes

IncludeDirective
Include directive for including markdown files. Syntax: ```{include} path/to/file.md ``` …
4

Include directive for including markdown files.

Syntax:

```{include} path/to/file.md
```

Or with line range:

```{include} path/to/file.md
:start-line: 5
:end-line: 20
```

Paths are resolved relative to:

  1. Current page's directory (if source_path available in state)
  2. Site root (if root_path available in state)
  3. Current working directory (fallback)

Security: Only allows paths within the site root to prevent path traversal.

Inherits from DirectivePlugin

Methods 1

parse
Parse include directive.
3 dict[str, Any] 
def parse(self, block: BlockParser, m: Match[str], state: BlockState) -> dict[str, Any]

Parse include directive.

Parameters 3
block BlockParser

Block parser
m Match[str]

Regex match object
state BlockState

Parser state (may contain root_path, source_path)
Returns

dict[str, Any] —

Token dict with type 'include'

Internal Methods 3
_resolve_path
Resolve file path relative to current page or site root. Security: - Rejec…
2 Path | None 
def _resolve_path(self, path: str, state: BlockState) -> Path | None

Resolve file path relative to current page or site root.

Security:

  • Rejects absolute paths
  • Rejects paths outside site root
  • Rejects symlinks (could escape containment)

Path Resolution:

  • root_path MUST be provided via state (set by rendering pipeline)
  • No fallback to Path.cwd() - eliminates CWD-dependent behavior
  • See: plan/active/rfc-path-resolution-architecture.md
Parameters 2
path str

Relative or absolute path to file
state BlockState

Parser state (must contain root_path, may contain source_path)
Returns

Path | None —

Resolved Path object, or None if not found, outside site root, or if root_path is not available in state

_load_file
Load file content, optionally with line range. Security: Enforces file size li…
3 str | None 
def _load_file(self, file_path: Path, start_line: int | None, end_line: int | None) -> str | None

Load file content, optionally with line range.

Security: Enforces file size limit to prevent memory exhaustion.

Parameters 3
file_path Path

Path to file
start_line int | None

Optional start line (1-indexed)
end_line int | None

Optional end line (1-indexed)
Returns

str | None —

File content as string, or None on error

__call__
Register include directive.
2 None 
def __call__(self, directive: Any, md: Any) -> None

Register include directive.

Parameters 2
directive Any
md Any

Functions

render_include
Render include directive.
2 str 
def render_include(renderer: Any, text: str, **attrs: Any) -> str

Render include directive.

Parameters 2

Name Type Default Description
renderer Any —

Mistune renderer
text str —

Rendered children (included markdown content) **attrs: Directive attributes

Returns

str —

HTML string