Module

rendering.plugins.directives.target

Target directive for explicit anchor targets.

Provides the {target} directive for creating anchor targets at arbitrary locations in content, enabling stable cross-references that survive content restructuring.

Architecture:

Part of the explicit anchor system (RFC-explicit-anchor-targets):
  • Heading {#id} syntax: Custom IDs on headings
  • {target} directive: Anchors anywhere in content (this module)
  • :name: option: Anchors on existing directives (Phase 3)

Syntax:

:::{target} my-anchor-id
:::

The target renders as an invisible anchor element (<span id="...">)
that can be referenced via [[#my-anchor-id]] cross-reference syntax.

Use Cases:

  • Anchor before a note/warning that users should link to
  • Stable anchor that survives heading text changes
  • Anchor in middle of content (not tied to heading)
  • Migration from Sphinx (.. _label: ) or MyST ((target)=) syntax

Related:

  • bengal/rendering/parsers/mistune.py: Heading {#id} syntax
  • bengal/rendering/plugins/cross_references.py: [[#anchor]] resolution
  • bengal/orchestration/content.py: xref_index["by_anchor"]
  • RFC: plan/active/rfc-explicit-anchor-targets.md
View source
2 Classes 1 Function

Classes

TargetOptions dataclass
Options for target directive. The target directive is intentionally simple - no options by default…
0

Options for target directive.

The target directive is intentionally simple - no options by default. The anchor ID is specified as the directive title.

Inherits from DirectiveOptions
TargetDirective
Create an explicit anchor target at any location. Syntax: :::{target} my-anchor-id ::: Th…
3

Create an explicit anchor target at any location.

Syntax:

:::{target} my-anchor-id
:::

The target renders as an invisible anchor element that can be referenced via [[#my-anchor-id]] cross-reference syntax.

Anchor ID Requirements:

  • Must start with a letter (a-z, A-Z)
  • May contain letters, numbers, hyphens, underscores
  • Case-sensitive in output, case-insensitive for resolution

Use Cases:

  • Anchor before a note/warning that users should link to
  • Stable anchor that survives content restructuring
  • **Migration from Sphinx's.. _label**: syntax
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_id
Validate anchor ID format.
1 str | None 
def validate_id(self, anchor_id: str) -> str | None

Validate anchor ID format.

Parameters 1
anchor_id str

The anchor ID to validate
Returns

str | None —

Error message if invalid, None if valid

parse_directive
Build target token from parsed components. The anchor ID is taken from the tit…
5 DirectiveToken 
def parse_directive(self, title: str, options: TargetOptions, content: str, children: list[Any], state: Any) -> DirectiveToken

Build target token from parsed components.

The anchor ID is taken from the title. Content is ignored since targets are point anchors, not containers.

Parameters 5
title str

The anchor ID (from directive title)
options TargetOptions

Parsed options (unused for target)
content str

Raw content inside directive (ignored)
children list[Any]

Parsed children (ignored)
state Any

Parser state
Returns

DirectiveToken —

DirectiveToken with anchor ID in attrs

render
Render target as invisible anchor element. The anchor renders as an empty <spa…
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render target as invisible anchor element.

The anchor renders as an empty <span> with the target ID. CSS class "target-anchor" allows styling if needed (e.g., scroll offset).

Parameters 2
renderer Any

Mistune renderer instance
text str

Rendered children (empty for targets) **attrs: Attributes from token (id, error)
Returns

str —

HTML anchor element (invisible by default)

Functions

render_target
Legacy render function for backward compatibility.
2 str 
def render_target(renderer: Any, text: str, **attrs: Any) -> str

Legacy render function for backward compatibility.

Parameters 2

Name Type Default Description
renderer Any —
text str —

Returns

str