# Theme Variables URL: /bengal/docs/0.4.3/reference/theme-variables/ Section: reference Tags: reference, templates, variables, kida -------------------------------------------------------------------------------- Theme Variables This reference lists all variables, objects, and functions available in Bengal templates. Global Objects These variables are available in all templates. site The global site object. Attribute Type Description site.title str Site title from config site.baseurl str Base URL (e.g., https://example.com) site.author str Site author name site.language str Language code (e.g., en) site.pages list[Page] All pages in the site site.regular_pages list[Page] Content pages only (no list pages) site.sections list[Section] Top-level sections site.taxonomies dict Map of taxonomies (tags, categories) site.data dict Data loaded from data/ directory site.config dict Full configuration object section Available on index pages (_index.md) and doc-type pages. Attribute Type Description section.name str Directory name section.title str Section title (from _index.md) section.index_page Page The section's _index.md page section.pages list[Page] Direct child pages section.sorted_pages list[Page] Pages sorted by weight/date section.subsections list[Section] Child sections section.metadata dict Frontmatter from _index.md Example: Auto-Generated Child Cards <div class="child-cards"> {% for subsection in section.subsections %} <a href="{{ subsection.index_page.href }}" class="card"> <h3>{{ subsection.title }}</h3> <p>{{ subsection.metadata.description }}</p> </a> {% end %} </div> Example: Section Navigation <nav class="section-nav"> <h4>In this section:</h4> <ul> {% for page in section.sorted_pages %} <li><a href="{{ page.href }}">{{ page.title }}</a></li> {% end %} </ul> </nav> page The current page being rendered. Attribute Type Description page.title str Page title page.nav_title str Short title for navigation (falls back to title) page.content str Raw content page.rendered_html str Rendered HTML content page.date datetime Publication date page.href str URL with baseurl applied (for display in templates) page._path str Site-relative URL without baseurl (for comparisons) page.slug str URL slug for the page page.metadata dict All frontmatter keys page.toc str Auto-generated Table of Contents HTML page.toc_items list[dict] Structured TOC data (id, title, level) page.is_home bool True if homepage page.is_section bool True if section index page.is_page bool True if regular page (not section) page.kind str Returns 'home', 'section', or 'page' page.type str Page type from frontmatter page.draft bool True if page is a draft page.description str Page description Navigation Properties Attribute Type Description page._section Section Parent section object (direct access to object tree) page.ancestors list[Section] Parent sections from root to current (for breadcrumbs) page.prev_in_section Page | None Previous page in section (by weight/date) page.next_in_section Page | None Next page in section (by weight/date) page.related_posts list[Page] Pages with matching tags Example: Custom Breadcrumbs <nav class="breadcrumbs"> <a href="/">Home</a> {% for ancestor in page.ancestors %} > <a href="{{ ancestor.href }}">{{ ancestor.title }}</a> {% end %} > <span>{{ page.title }}</span> </nav> Example: Prev/Next Navigation <nav class="prev-next"> {% if page.prev_in_section %} <a href="{{ page.prev_in_section.href }}">← {{ page.prev_in_section.title }}</a> {% end %} {% if page.next_in_section %} <a href="{{ page.next_in_section.href }}">{{ page.next_in_section.title }} →</a> {% end %} </nav> Example: Related Posts {% if page.related_posts %} <aside class="related"> <h3>Related Articles</h3> <ul> {% for post in page.related_posts[:5] %} <li><a href="{{ post.href }}">{{ post.title }}</a></li> {% end %} </ul> </aside> {% end %} URL Properties Bengal provides two URL properties with clear purposes: page.href - Primary property for display Automatically includes baseurl (e.g., /bengal/docs/page/) Use in <a href>, <link>, <img src> attributes Works correctly for all deployment scenarios (GitHub Pages, Netlify, S3, etc.) page._path - For comparisons and logic Site-relative URL without baseurl (e.g., /docs/page/) Use for comparisons: {% if page._path == '/docs/' %} Use for menu activation, filtering, and conditional logic NEVER use in template href attributes Example: Usage {# Display URL (includes baseurl) #} <a href="{{ page.href }}">{{ page.title }}</a> {# Comparison (without baseurl) #} {% if page._path == '/docs/' %} <span class="active">Current Section</span> {% end %} {# url_for() also works for URL generation #} <a href="{{ url_for(page) }}">{{ page.title }}</a> Why This Pattern? Ergonomic: Templates use /bengal/docs/0.4.3/reference/theme-variables/ for display - it "just works" Clear: _path makes comparisons explicit (without baseurl) No wrappers: Page objects handle baseurl via their _site reference Works everywhere: Supports file://, S3, GitHub Pages, Netlify, Vercel, etc. Global Functions Functions available in all templates. asset_url(path) Generates a fingerprint-aware URL for an asset. <link rel="stylesheet" href="{{ asset_url('css/style.css') }}"> <!-- Outputs: /assets/css/style.a1b2c3d4.css --> url_for(target, page=none, version="current", baseurl=true) Generates a URL for a page, section, snapshot, or literal path. Applies baseurl automatically and keeps section links version-aware in multi-version docs. <a href="{{ url_for(page) }}">Link</a> <a href="{{ url_for('/docs/getting-started/') }}">Getting Started</a> <a href="{{ url_for(section, page) }}">Current-version section</a> dateformat(date, format) Formats a date object. {{ dateformat(page.date, "%B %d, %Y") }} get_menu(menu_name) Retrieves a navigation menu. {% for item in get_menu('main') %} <a href="{{ item.url }}">{{ item.name }}</a> {% end %} Template Helpers Bengal includes categorized helper modules: Strings: truncate, slugify, markdownify Collections: where, group_by, sort_by Dates: time_ago, date_iso Images: image_processed, image_url Taxonomies: related_posts, popular_tags Tip Tip Debugging You can inspect available variables by printing them in a comment: <!-- {{ page.metadata }} --> -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 764 - Reading Time: 4 minutes