literalinclude

rendering.plugins.directives.literalinclude

Literal include directive for Mistune.

Allows including code files directly in content as code blocks.

Syntax:

```{literalinclude} path/to/file.py
```

Or with options:

```{literalinclude} path/to/file.py
:language: python
:start-line: 5
:end-line: 20
:emphasize-lines: 7,8,9
:linenos: true
```

Robustness:

File size limits to prevent memory exhaustion (10MB default)
Symlink rejection to prevent path traversal attacks

Classes

LiteralIncludeDirective

Literal include directive for including code files as code blocks. Syntax: ```{literalinclude}…

Literal include directive for including code files as code blocks.

Syntax:

```{literalinclude} path/to/file.py
```

Or with options:

```{literalinclude} path/to/file.py
:language: python
:start-line: 5
:end-line: 20
:emphasize-lines: 7,8,9
:linenos: true
```

Paths are resolved relative to:

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

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

Inherits from DirectivePlugin

Methods 1

parse

Parse literalinclude directive.

3 dict[str, Any]

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

Parse literalinclude 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 'literalinclude'

Internal Methods 4

_detect_language

Detect language from file extension.

1 str | None

def _detect_language(self, path: str) -> str | None

Detect language from file extension.

Parameters 1

path

str

File path

Returns

str | None —

Language name or None

_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 and emphasis. Security: Enforces…

4 str | None

def _load_file(self, file_path: Path, start_line: int | None, end_line: int | None, emphasize_lines: str | None) -> str | None

Load file content, optionally with line range and emphasis.

Security: Enforces file size limit to prevent memory exhaustion.

Parameters 4

`file_path`	`Path`	Path to file
`start_line`	`int \| None`	Optional start line (1-indexed)
`end_line`	`int \| None`	Optional end line (1-indexed)
`emphasize_lines`	`str \| None`	Optional comma-separated line numbers to emphasize

Returns

str | None —

File content as string, or None on error

__call__

2 None

def __call__(self, directive: Any, md: Any) -> None

Parameters 2

`directive`	`Any`
`md`	`Any`

Functions

render_literalinclude

Render literalinclude directive as code block.

2 str

def render_literalinclude(renderer: Any, text: str, **attrs: Any) -> str

Render literalinclude directive as code block.

Parameters 2

Name	Type	Default	Description
`renderer`	`Any`	—	Mistune renderer
`text`	`str`	—	Not used (content is in attrs['code']) **attrs: Directive attributes

Returns

str —

HTML string