# menu URL: /api/core/menu/ Section: core -------------------------------------------------------------------------------- menu - Bengal window.BENGAL_THEME_DEFAULTS = { appearance: 'dark', palette: 'snow-lynx' }; // Progressive Enhancement System Configuration window.Bengal = window.Bengal || {}; window.Bengal.enhanceBaseUrl = '/bengal/assets/js/enhancements'; window.Bengal.watchDom = true; window.Bengal.debug = false; (function () { try { var defaults = window.BENGAL_THEME_DEFAULTS || { appearance: 'system', palette: '' }; var defaultAppearance = defaults.appearance; if (defaultAppearance === 'system') { defaultAppearance = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'; } var storedTheme = localStorage.getItem('bengal-theme'); var storedPalette = localStorage.getItem('bengal-palette'); var theme = storedTheme ? (storedTheme === 'system' ? defaultAppearance : storedTheme) : defaultAppearance; var palette = storedPalette ?? defaults.palette; document.documentElement.setAttribute('data-theme', theme); if (palette) { document.documentElement.setAttribute('data-palette', palette); } } catch (e) { document.documentElement.setAttribute('data-theme', 'light'); } })(); Skip to main content Magnifying Glass ESC Recent Clear Magnifying Glass No results for "" Try different keywords or check your spelling Start typing to search... ↑↓ Navigate ↵ Open ESC Close Powered by Lunr ᓚᘏᗢ Documentation Info About Arrow Clockwise Get Started Note Tutorials File Text Content Palette Theming Settings Building Starburst Extending Bookmark Reference Learning Tracks Releases Dev GitHub API Reference bengal CLI Magnifying Glass Search ⌘K Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal List ᓚᘏᗢ Magnifying Glass Search X Close Documentation Info About Arrow Clockwise Get Started Note Tutorials File Text Content Palette Theming Settings Building Starburst Extending Bookmark Reference Learning Tracks Releases Dev GitHub API Reference bengal CLI Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal API Reference __main__ bengal Caret Right Folder Analysis community_detection graph_analysis graph_reporting graph_visualizer knowledge_graph link_suggestions link_types page_rank path_analysis performance_advisor results Caret Right Folder Assets manifest pipeline Caret Right Folder Autodoc base config docstring_parser utils virtual_orchestrator Caret Right Folder Extractors cli openapi python Caret Right Folder Models cli common openapi python Caret Right Folder Cache asset_dependency_map cache_store cacheable compression dependency_tracker page_discovery_cache query_index query_index_registry taxonomy_index utils Caret Right Folder Build Cache autodoc_tracking core file_tracking fingerprint parsed_content_cache rendered_output_cache taxonomy_index_mixin validation_cache Caret Right Folder Indexes author_index category_index date_range_index section_index Caret Right Folder Cli __main__ base site_templates utils Caret Right Folder Commands assets build clean collections config debug explain fix health init perf project serve site skeleton sources theme utils validate Caret Right Folder Graph __main__ bridges communities orphans pagerank report suggest Caret Right Folder New config presets scaffolds site wizard Caret Right Folder Helpers cli_app_loader cli_output config_validation error_handling menu_config metadata progress site_loader traceback validation Caret Right Folder Skeleton hydrator schema Caret Right Folder Templates base registry Caret Right Folder Blog template Caret Right Folder Changelog template Caret Right Folder Default template Caret Right Folder Docs template Caret Right Folder Landing template Caret Right Folder Portfolio template Caret Right Folder Resume template Caret Right Folder Collections errors loader schemas validator Caret Right Folder Config defaults deprecation directory_loader env_overrides environment feature_mappings hash loader merge origin_tracker validators Caret Right Folder Content Layer entry loaders manager source Caret Right Folder Sources github local notion rest Caret Right Folder Content Types base registry strategies Caret Right Folder Core build_context cascade_engine menu section theme Caret Right Folder Asset asset_core css_transforms Caret Right Folder Page computed content metadata navigation operations page_core proxy relationships utils Caret Right Folder Site core data discovery factories page_caches properties section_registry theme Caret Right Folder Debug base config_inspector content_migrator delta_analyzer dependency_visualizer explainer incremental_debugger models reporter shortcode_sandbox Caret Right Folder Discovery asset_discovery content_discovery Caret Right Folder Fonts downloader generator Caret Right Folder Health autofix base health_check report Caret Right Folder Linkcheck async_checker ignore_policy internal_checker models orchestrator Caret Right Folder Validators anchors assets cache config connectivity cross_ref fonts links menu navigation output performance rendering rss sitemap taxonomy tracks Caret Right Folder Directives analysis checkers constants Caret Right Folder Orchestration asset content full_to_incremental incremental menu postprocess related_posts render section static streaming taxonomy Caret Right Folder Postprocess html_output redirects rss sitemap special_pages Caret Right Folder Output Formats index_generator json_generator llm_generator lunr_index_generator txt_generator utils Caret Right Folder Rendering api_doc_enhancer asset_extractor errors jinja_utils link_transformer link_validator pygments_cache renderer template_context template_profiler validator Caret Right Folder Parsers base factory mistune native_html pygments_patch python_markdown Caret Right Folder Pipeline core output thread_local toc transforms Caret Right Folder Plugins badges cross_references inline_icon term variable_substitution Caret Right Folder Directives _icons admonitions badge base button cache cards checklist code_tabs container contracts data_table dropdown embed errors example_label fenced figure glossary icon include list_table literalinclude marimo navigation options rubric steps tabs target term terminal tokens utils validator video Caret Right Folder Template Engine asset_url core environment manifest menu url_helpers Caret Right Folder Template Functions advanced_collections advanced_strings autodoc collections content crossref data dates debug files get_page i18n icons images math_functions navigation pagination_helpers seo strings tables taxonomies theme urls Caret Right Folder Server build_handler component_preview constants dev_server live_reload pid_manager reload_controller request_handler request_logger resource_manager utils Caret Right Folder Services validation Caret Right Folder Themes config Caret Right Folder Utils atomic_write autodoc build_context build_stats build_summary cli_output css_minifier dates dotdict error_handlers file_io file_lock hashing incremental_constants js_bundler live_progress logger metadata observability page_initializer pagination path_resolver paths performance_collector performance_report profile progress retry rich_console sections swizzle text theme_registry theme_resolution thread_local traceback_config traceback_renderer url_normalization url_strategy API Reference Core ᗢ Caret Down Link Copy URL External Open LLM text Copy Copy LLM text Share with AI Ask Claude Ask ChatGPT Ask Gemini Ask Copilot Module core.menu Menu system for navigation and site structure. Provides menu building from configuration, page frontmatter, and section hierarchy. Supports hierarchical menus, active state tracking, and i18n localization. Menus are built during content discovery and cached for template access. Key Concepts: Menu sources: Config files, page frontmatter, section structure Hierarchical menus: Parent-child relationships with weight-based sorting Active state: Current page and active trail tracking i18n menus: Localized menu variants per language Related Modules: bengal.orchestration.menu: Menu building orchestration bengal.core.site: Site container that holds menus bengal.rendering.template_functions.navigation: Template access to menus See Also: bengal/core/menu.py: MenuItem class for menu item representation bengal/core/menu.py: MenuBuilder class for menu construction View source 2 Classes Classes MenuItem dataclass Represents a single menu item with optional hierarchy. Menu items form hierarchical navigation str… 5 Caret Right Represents a single menu item with optional hierarchy. Menu items form hierarchical navigation structures with parent-child relationships. Items can be marked as active based on current page URL, and support weight-based sorting for display order. Creation: Config file: Explicit menu definitions in bengal.toml Page frontmatter: Pages register themselves via menu metadata Section structure: Auto-generated from section hierarchy Attributes Name Type Description name str Display name for the menu item url str URL path for the menu item weight int Sort weight (lower values appear first) parent str | None Parent menu identifier (for hierarchical menus) identifier str | None Unique identifier (auto-generated from name if not provided) icon str | None Icon name from frontmatter (e.g., 'book', 'folder', 'terminal') children list[MenuItem] Child menu items (populated during menu building) active bool Whether this item matches the current page URL active_trail bool Whether this item is in the active path (has active child) Relationships — Used by: MenuBuilder for menu construction - Used by: MenuOrchestrator for menu building - Used in: Templates via site.menu for navigation rendering Methods 4 add_child Add a child menu item and sort children by weight. Adds the child to the child… 1 None Caret Right def add_child(self, child: MenuItem) -> None Add a child menu item and sort children by weight. Adds the child to the children list and immediately sorts all children by weight (ascending). Lower weights appear first in the list. Parameters 1 child MenuItem MenuItem to add as a child mark_active Mark this item as active if URL matches current page. Recursively checks this … 1 bool Caret Right def mark_active(self, current_url: str) -> bool Mark this item as active if URL matches current page. Recursively checks this item and all children for URL matches. Sets active flag if this item matches, and active_trail flag if any child matches. URLs are normalized (trailing slashes removed) before comparison. Parameters 1 current_url str Current page URL to match against (will be normalized) Returns bool — True if this item or any child is active, False otherwise reset_active Reset active states for this item and all children. Recursively clears `active… 0 None Caret Right def reset_active(self) -> None Reset active states for this item and all children. Recursively clears active and active_trail flags. Called before each page render to ensure fresh state for active item detection. to_dict Convert menu item to dictionary for template access. Creates a dictionary repr… 0 dict[str, Any] Caret Right def to_dict(self) -> dict[str, Any] Convert menu item to dictionary for template access. Creates a dictionary representation suitable for JSON serialization and template rendering. Recursively converts children to dictionaries. Returns dict[str, Any] — Dictionary with name, url, icon, active, active_trail, and children fields. Children are recursively converted to dictionaries. Internal Methods 1 Caret Right __post_init__ Set identifier from name if not provided. Automatically generates a slug-like … 0 None Caret Right def __post_init__(self) -> None Set identifier from name if not provided. Automatically generates a slug-like identifier from the menu item name by lowercasing and replacing spaces/underscores with hyphens. This ensures every menu item has a unique identifier for parent-child relationships. MenuBuilder Builds hierarchical menu structures from various sources. Constructs menu hierarchies from config … 9 Caret Right Builds hierarchical menu structures from various sources. Constructs menu hierarchies from config definitions, page frontmatter, and section structure. Handles deduplication, cycle detection, and hierarchy building with parent-child relationships. Creation: Direct instantiation: MenuBuilder() Created by MenuOrchestrator for menu building Fresh instance created for each menu build Attributes Name Type Description items — List of MenuItem objects (flat list before hierarchy building) _seen_identifiers — Set of seen identifiers for deduplication _seen_urls — Set of seen URLs for deduplication _seen_names — Set of seen names for deduplication Behavior Notes: - Identifiers: Each MenuItem has an identifier (slug from name by default). Parent references use identifiers. - Cycle detection: build_hierarchy() detects circular references and raises ValueError when a cycle is found. Consumers should surface this early as a configuration error. - Deduplication: Automatically prevents duplicate items by identifier, URL, and name. Relationships — Uses: MenuItem for menu item representation - Used by: MenuOrchestrator for menu building - Used in: Menu building during content discovery phase Methods 4 add_from_config Add menu items from configuration file. Parses menu configuration from bengal.… 1 None Caret Right def add_from_config(self, menu_config: list[dict[str, Any]]) -> None Add menu items from configuration file. Parses menu configuration from bengal.toml or config files and creates MenuItem objects. Skips duplicates automatically and logs debug messages for skipped items. Parameters 1 menu_config list[dict[str, Any]] List of menu item dictionaries from config file. Each dict should have: name, url, weight (optional), parent (optional), identifier (optional) add_from_page Add a page to menu based on frontmatter metadata. Creates a MenuItem from page… 3 None Caret Right def add_from_page(self, page: Any, menu_name: str, menu_config: dict[str, Any]) -> None Add a page to menu based on frontmatter metadata. Creates a MenuItem from page frontmatter menu configuration. Uses page's relative_url for menu item URL (baseurl applied in templates). Skips duplicates automatically. Parameters 3 page Any Page object with frontmatter menu configuration menu_name str Name of the menu (e.g., 'main', 'footer'). Currently used for logging, all menus share same builder menu_config dict[str, Any] Menu configuration dictionary from page frontmatter. Should have: name (optional, defaults to page.title), url (optional, defaults to page.relative_url), weight (optional), parent (optional), identifier (optional) build_hierarchy Build hierarchical tree from flat list with validation. Converts flat list of … 0 list[MenuItem] Caret Right def build_hierarchy(self) -> list[MenuItem] Build hierarchical tree from flat list with validation. Converts flat list of MenuItem objects into hierarchical tree structure based on parent-child relationships. Validates parent references and detects circular dependencies. Process: 1. Create lookup map by identifier 2. Validate parent references (warn about orphaned items) 3. Build parent-child relationships 4. Detect cycles (raises ValueError if found) 5. Return root items (items with no parent) Returns list[MenuItem] — List of root MenuItem objects (no parent) with children populated. Empty list if no items or all items have parents. mark_active_items Mark active items in menu tree based on current page URL. Recursively marks me… 2 None Caret Right def mark_active_items(self, current_url: str, menu_items: list[MenuItem]) -> None Mark active items in menu tree based on current page URL. Recursively marks menu items as active if their URL matches the current page URL. Also marks items in the active trail (items with active children). Resets all active states before marking to ensure clean state. Parameters 2 current_url str Current page URL to match against (will be normalized) menu_items list[MenuItem] List of root MenuItem objects to process (hierarchical tree) Internal Methods 5 Caret Right __init__ 0 None Caret Right def __init__(self) -> None _is_duplicate Check if an item is a duplicate based on identifier, URL, or name. Checks agai… 3 bool Caret Right def _is_duplicate(self, item_id: str | None, item_url: str, item_name: str) -> bool Check if an item is a duplicate based on identifier, URL, or name. Checks against previously seen identifiers, URLs, and names to prevent duplicate menu items. An item is considered duplicate if any of these match a previously added item. Parameters 3 item_id str | None Item identifier (if any). None is valid (not checked). item_url str Item URL (normalized, trailing slash removed). item_name str Item name (lowercased for case-insensitive comparison). Returns bool — True if duplicate found (identifier, URL, or name matches), False otherwise _track_item Track an item to prevent future duplicates. Adds the item's identifier, URL, a… 1 None Caret Right def _track_item(self, item: MenuItem) -> None Track an item to prevent future duplicates. Adds the item's identifier, URL, and name to the seen sets for duplicate detection. Called automatically when items are added via add_from_config() or add_from_page(). Parameters 1 item MenuItem MenuItem to track _has_cycle Detect circular references in menu tree using DFS. Uses depth-first search to … 3 bool Caret Right def _has_cycle(self, item: MenuItem, visited: set[str], path: set[str]) -> bool Detect circular references in menu tree using DFS. Uses depth-first search to detect cycles in parent-child relationships. A cycle exists if an item appears in its own descendant chain. Parameters 3 item MenuItem Current menu item being checked visited set[str] Set of all visited identifiers (for optimization) path set[str] Current path identifiers from root to current item (for cycle detection) Returns bool — True if cycle detected (item appears in its own descendant chain), False otherwise Algorithm: If item.identifier in path: cycle detected Add item to path and visited Recursively check all children Return True if any child has cycle _get_depth Get maximum depth of menu tree from this item. Recursively calculates the maxi… 1 int Caret Right def _get_depth(self, item: MenuItem) -> int Get maximum depth of menu tree from this item. Recursively calculates the maximum depth of the menu tree starting from the given item. Used for logging and validation. Parameters 1 item MenuItem Root menu item to calculate depth from Returns int — Maximum depth as integer: 1: Item has no children 2: Item has children but no grandchildren N: Maximum depth of deepest descendant ← Previous core Next → section List © 2025 Bengal ᓚᘏᗢ window.BENGAL_LAZY_ASSETS = { tabulator: '/bengal/assets/js/tabulator.min.js', dataTable: '/bengal/assets/js/data-table.js', mermaidToolbar: '/bengal/assets/js/mermaid-toolbar.9de5abba.js', mermaidTheme: '/bengal/assets/js/mermaid-theme.344822c5.js', graphMinimap: '/bengal/assets/js/graph-minimap.cc7e42e3.js', graphContextual: '/bengal/assets/js/graph-contextual.440e59c6.js' }; window.BENGAL_ICONS = { close: '/bengal/assets/icons/close.911d4fe1.svg', enlarge: '/bengal/assets/icons/enlarge.652035e5.svg', copy: '/bengal/assets/icons/copy.3d56e945.svg', 'download-svg': '/bengal/assets/icons/download.04f07e1b.svg', 'download-png': '/bengal/assets/icons/image.c34dfd40.svg', 'zoom-in': '/bengal/assets/icons/zoom-in.237b4a83.svg', 'zoom-out': '/bengal/assets/icons/zoom-out.38857c77.svg', reset: '/bengal/assets/icons/reset.d26dba29.svg' }; Arrow Up X -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 2549 - Reading Time: 13 minutes