Module

core.page.metadata

Page Metadata Mixin - Basic properties and type checking.

View source
1 Class

Classes

PageMetadataMixin
Mixin providing metadata properties and type checking for pages. This mixin handles: - Basic prope…
27

Mixin providing metadata properties and type checking for pages.

This mixin handles:

  • Basic properties: title, date, slug, url
  • Type checking: is_home, is_section, is_page, kind
  • Simple metadata: description, draft, keywords
  • Component Model: type, variant, props
  • TOC access: toc_items (lazy evaluation)

Attributes

Name Type Description
metadata dict[str, Any]
source_path Path
output_path Path | None
toc str | None
core PageCore | None
_site Any
_toc_items_cache list[dict[str, Any]] | None

Methods 26

title property
Get page title from metadata or generate intelligently from context. For index…
str 
def title(self) -> str

Get page title from metadata or generate intelligently from context.

For index pages (_index.md or index.md) without explicit titles, uses the parent directory name humanized instead of showing "Index" which is not user-friendly in menus, navigation, or page titles.

Returns

str

date property
Get page date from metadata. Uses bengal.utils.dates.parse_date for flexible d…
datetime | None 
def date(self) -> datetime | None

Get page date from metadata.

Uses bengal.utils.dates.parse_date for flexible date parsing.

Returns

datetime | None

slug property
Get URL slug for the page.
str 
def slug(self) -> str

Get URL slug for the page.

Returns

str

relative_url property
Get relative URL without baseurl (for comparisons). This is the identity URL -…
str 
def relative_url(self) -> str

Get relative URL without baseurl (for comparisons).

This is the identity URL - use for comparisons, menu activation, etc. Always returns a relative path without baseurl.

Returns

str

url property
Get URL with baseurl applied (cached after first access). This is the primary …
str 
def url(self) -> str

Get URL with baseurl applied (cached after first access).

This is the primary URL property for templates - automatically includes baseurl when available. Use .relative_url for comparisons.

Returns

str —

URL path with baseurl prepended (if configured)

permalink property
Alias for url (for backward compatibility). Both url and permalink now return …
str 
def permalink(self) -> str

Alias for url (for backward compatibility).

Both url and permalink now return the same value (with baseurl). Use .relative_url for comparisons.

Returns

str

toc_items property
Get structured TOC data (lazy evaluation). Only extracts TOC structure when ac…
list[dict[str, Any]] 
def toc_items(self) -> list[dict[str, Any]]

Get structured TOC data (lazy evaluation).

Only extracts TOC structure when accessed by templates, saving HTMLParser overhead for pages that don't use toc_items.

Important: This property does NOT cache empty results. This allows toc_items to be accessed before parsing (during xref indexing) without preventing extraction after parsing when page.toc is actually set.

Returns

list[dict[str, Any]] —

List of TOC items with id, title, and level

is_home property
Check if this page is the home page.
bool 
def is_home(self) -> bool

Check if this page is the home page.

Returns

bool —

True if this is the home page

is_section property
Check if this page is a section page.
bool 
def is_section(self) -> bool

Check if this page is a section page.

Returns

bool —

True if this is a section (always False for Page, True for Section)

is_page property
Check if this is a regular page (not a section).
bool 
def is_page(self) -> bool

Check if this is a regular page (not a section).

Returns

bool —

True if this is a regular page

kind property
Get the kind of page: 'home', 'section', or 'page'.
str 
def kind(self) -> str

Get the kind of page: 'home', 'section', or 'page'.

Returns

str —

String indicating page kind

type property
Get page type from core metadata (preferred) or frontmatter. Component Model: …
str | None 
def type(self) -> str | None

Get page type from core metadata (preferred) or frontmatter.

Component Model: Identity.

Returns

str | None —

Page type or None

description property
Get page description from core metadata (preferred) or frontmatter.
str 
def description(self) -> str

Get page description from core metadata (preferred) or frontmatter.

Returns

str —

Page description or empty string

variant property
Get visual variant from core (preferred) or legacy layout/hero_style fields. T…
str | None 
def variant(self) -> str | None

Get visual variant from core (preferred) or legacy layout/hero_style fields.

This normalizes 'layout' and 'hero_style' into the new Component Model 'variant'.

Component Model: Mode.

Returns

str | None —

Variant string or None

props property
Get page props (alias for metadata). Component Model: Data.
dict[str, Any] 
def props(self) -> dict[str, Any]

Get page props (alias for metadata).

Component Model: Data.

Returns

dict[str, Any] —

Page metadata dictionary

draft property
Check if page is marked as draft.
bool 
def draft(self) -> bool

Check if page is marked as draft.

Returns

bool —

True if page is a draft

keywords property
Get page keywords from metadata.
list[str] 
def keywords(self) -> list[str]

Get page keywords from metadata.

Returns

list[str] —

List of keywords

hidden property
Check if page is hidden (unlisted). Hidden pages: - Are excluded from navigati…
bool 
def hidden(self) -> bool

Check if page is hidden (unlisted).

Hidden pages:

  • Are excluded from navigation menus
  • Are excluded from site.pages queries (listings)
  • Are excluded from sitemap.xml
  • Get noindex,nofollow robots meta
  • Still render and are accessible via direct URL
Returns

bool —

True if page is hidden

visibility property
Get visibility settings with defaults. The visibility object provides granular…
dict[str, Any] 
def visibility(self) -> dict[str, Any]

Get visibility settings with defaults.

The visibility object provides granular control over page visibility:

  • menu: Include in navigation menus (default: True)
  • listings: Include in site.pages queries (default: True)
  • sitemap: Include in sitemap.xml (default: True)
  • robots: Robots meta directive (default: "index, follow")
  • render: When to render - "always", "local", "never" (default: "always")
  • search: Include in search index (default: True)
  • rss: Include in RSS feeds (default: True)

Ifhidden: trueis set, it expands to restrictive defaults.

Returns

dict[str, Any] —

Dict with visibility settings

in_listings property
Check if page should appear in listings/queries. Excludes drafts and pages wit…
bool 
def in_listings(self) -> bool

Check if page should appear in listings/queries.

Excludes drafts and pages with visibility.listings=False.

Returns

bool —

True if page should appear in site.pages queries

in_sitemap property
Check if page should appear in sitemap. Excludes drafts and pages with visibil…
bool 
def in_sitemap(self) -> bool

Check if page should appear in sitemap.

Excludes drafts and pages with visibility.sitemap=False.

Returns

bool —

True if page should appear in sitemap.xml

in_search property
Check if page should appear in search index. Excludes drafts and pages with vi…
bool 
def in_search(self) -> bool

Check if page should appear in search index.

Excludes drafts and pages with visibility.search=False.

Returns

bool —

True if page should appear in search index

in_rss property
Check if page should appear in RSS feeds. Excludes drafts and pages with visib…
bool 
def in_rss(self) -> bool

Check if page should appear in RSS feeds.

Excludes drafts and pages with visibility.rss=False.

Returns

bool —

True if page should appear in RSS feeds

robots_meta property
Get robots meta content for this page.
str 
def robots_meta(self) -> str

Get robots meta content for this page.

Returns

str —

Robots directive string (e.g., "index, follow" or "noindex, nofollow")

should_render property
Check if page should be rendered based on visibility.render setting. Note: Thi…
bool 
def should_render(self) -> bool

Check if page should be rendered based on visibility.render setting.

Note: This checks the render setting but doesn't know about environment. Use should_render_in_environment() for environment-aware checks.

Returns

bool —

True if render is not "never"

should_render_in_environment
Check if page should be rendered in the given environment.
1 bool 
def should_render_in_environment(self, is_production: bool = False) -> bool

Check if page should be rendered in the given environment.

Parameters 1
is_production bool

True if building for production
Returns

bool —

True if page should be rendered in this environment

Internal Methods 1
_fallback_url
Generate fallback URL when output_path or site not available. Used during page…
0 str 
def _fallback_url(self) -> str

Generate fallback URL when output_path or site not available.

Used during page construction before output_path is determined.

Returns

str —

URL based on slug