Module

rendering.plugins.directives.navigation

Navigation directives for Bengal SSG.

Provides directives that leverage the pre-computed site tree:

  • breadcrumbs: Auto-generate breadcrumb navigation from page.ancestors
  • siblings: Show other pages in the same section
  • prev-next: Section-aware previous/next navigation
  • related: Show related content based on tags

Architecture:

Migrated to BengalDirective base class as part of directive system v2.
All directives access renderer._current_page to walk the object tree.
View source
8 Classes 5 Functions

Classes

BreadcrumbsOptions dataclass
Options for breadcrumbs directive.
0

Options for breadcrumbs directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
separator str

Separator character between items (default: ›)
show_home bool

Whether to show home link (default: true)
home_text str

Text for home link (default: Home)
home_url str

URL for home link (default: /)
_field_aliases ClassVar[dict[str, str]]
BreadcrumbsDirective
Auto-generate breadcrumb navigation from page ancestors. Syntax: :::{breadcrumbs} :separat…
2

Auto-generate breadcrumb navigation from page ancestors.

Syntax:

:::{breadcrumbs}
:separator: /
:show-home: true
:home-text: Home
:::
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]]

Methods 2

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

Build breadcrumbs token.

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

DirectiveToken

render
Render breadcrumb navigation from page ancestors.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render breadcrumb navigation from page ancestors.

Parameters 2
renderer Any
text str
Returns

str

SiblingsOptions dataclass
Options for siblings directive.
0

Options for siblings directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
limit int

Maximum number of siblings to show (0 = no limit)
exclude_current bool

Whether to exclude current page
show_description bool

Whether to show page descriptions
_field_aliases ClassVar[dict[str, str]]
SiblingsDirective
Show other pages in the same section. Syntax: :::{siblings} :limit: 10 :exclude-curren…
2

Show other pages in the same section.

Syntax:

:::{siblings}
:limit: 10
:exclude-current: true
:show-description: true
:::
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]]

Methods 2

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

Build siblings token.

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

DirectiveToken

render
Render sibling pages in the same section.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render sibling pages in the same section.

Parameters 2
renderer Any
text str
Returns

str

PrevNextOptions dataclass
Options for prev-next directive.
0

Options for prev-next directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
show_title bool

Whether to show page titles
show_section bool

Whether to show section names
_field_aliases ClassVar[dict[str, str]]
PrevNextDirective
Section-aware previous/next navigation. Syntax: :::{prev-next} :show-title: true :show…
2

Section-aware previous/next navigation.

Syntax:

:::{prev-next}
:show-title: true
:show-section: false
:::
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]]

Methods 2

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

Build prev-next token.

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

DirectiveToken

render
Render previous/next navigation links.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render previous/next navigation links.

Parameters 2
renderer Any
text str
Returns

str

RelatedOptions dataclass
Options for related directive.
0

Options for related directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
limit int

Maximum number of related items (default: 5)
title str

Section title (default: Related Articles)
show_tags bool

Whether to show tags
_field_aliases ClassVar[dict[str, str]]
RelatedDirective
Show related content based on tags. Syntax: :::{related} :limit: 5 :title: Related Art…
2

Show related content based on tags.

Syntax:

:::{related}
:limit: 5
:title: Related Articles
:show-tags: true
:::
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]]

Methods 2

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

Build related token.

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

DirectiveToken

render
Render related content based on tags.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render related content based on tags.

Parameters 2
renderer Any
text str
Returns

str

Functions

_get_section_url
Get URL for a section.
1 str 
def _get_section_url(section: Any) -> str

Get URL for a section.

Parameters 1

Name Type Default Description
section Any —

Returns

str

render_breadcrumbs
Legacy render function for backward compatibility.
2 str 
def render_breadcrumbs(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

render_siblings
Legacy render function for backward compatibility.
2 str 
def render_siblings(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

render_prev_next
Legacy render function for backward compatibility.
2 str 
def render_prev_next(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

render_related
Legacy render function for backward compatibility.
2 str 
def render_related(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