infrahub-managing-menus

name	infrahub-managing-menus
description	Creates Infrahub custom navigation menus for the web UI sidebar, organizing node types into logical groups. TRIGGER when: designing sidebar menus, grouping node types in UI, customizing Infrahub web interface navigation. DO NOT TRIGGER when: designing schemas, writing checks or transforms, populating data objects.
allowed-tools	["Read","Write","Edit","Bash"]
argument-hint	[menu-structure-description]
metadata	{"version":"1.2.7","author":"OpsMill"}

Infrahub Menu Creator

Overview

Expert guidance for creating Infrahub custom menus. Menus control the left-side navigation in the web interface, organizing schema node types into a custom hierarchy.

Project Context

Existing menu files: !find . -name "*.yml" -path "*/menus/*" 2>/dev/null | head -10

Schema files (to identify available node types): !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10

When to Use

• Designing navigation menus for the Infrahub web UI
• Organizing node types into logical groups and hierarchies
• Adding icons and labels to menu items
• Setting up group headers (non-clickable) with nested children
• Configuring schema nodes to use custom menus instead of auto-generated ones

Rule Categories

Priority	Category	Prefix	Description
CRITICAL	Format	format-	apiVersion, kind, spec
CRITICAL	Properties	item-	name, namespace, label, kind
HIGH	Hierarchy	hierarchy-	Nesting, group headers, data
HIGH	Icons	icons-	MDI icon reference, choices
MEDIUM	Schema	schema-	include_in_menu, kind links
LOW	Patterns	patterns-	Flat menu, comments, links

Schema Features This Skill Depends On

A custom menu doesn't replace the auto-menu — it augments it. Schemas need cooperating settings to avoid duplicates and stay UI-stable.

If the menu item...	The schema must...	See
Links to a schema node's list view via kind:	Define that node (or generic) so the URL resolves — and set include_in_menu: false on it to suppress the duplicate auto-menu entry	rules/schema-integration.md
Shows all subtypes under one entry via a generic kind	Have the generic defined, with all the relevant nodes inherit_from it	../infrahub-managing-schemas/rules/hierarchy-setup.md
Should appear at a specific position when auto-menu is in play	Set order_weight on the schema node (auto-menu uses it; custom menu ignores it)	../infrahub-managing-schemas/rules/display-order-weight.md
Groups subtypes under a parent node entry	Set menu_placement: <FullKind> on each subtype so the auto-menu side groups consistently with the custom menu	../infrahub-managing-schemas/rules/display-menu-placement.md

Audit include_in_menu on every node you reference from the menu file — the sidebar duplicates that this prevents look to users like the custom menu is "broken", but the fix is on the schema side.

Menu File Basics

---
apiVersion: infrahub.app/v1
kind: Menu
spec:
  data:
    - namespace: Dcim
      name: DeviceMenu
      label: "Devices"
      icon: "mdi:server"
      kind: DcimDevice        # Links to schema node list view

apiVersion, kind: Menu, and spec.data are always required. Each menu item needs name and namespace.

Workflow

Follow these steps when creating a menu:

1. Gather requirements — Ask what schema nodes exist, how they should be grouped, and whether the user wants flat or hierarchical navigation.

2. Read relevant rules — Read rules/format-structure.md for the required YAML structure, rules/item-properties.md for item fields, and rules/hierarchy-nesting.md if nesting is needed. Read rules/icons-reference.md to pick appropriate MDI icons.

3. Generate the menu YAML — Start with the $schema comment and apiVersion/kind/spec structure. Apply rules from step 2.

4. Add registration and schema guidance — Every menu file output must include:

   • A YAML comment block showing how to register the file in .infrahub.yml under the menus: key (see rules/format-structure.md)
   • A YAML comment block advising to set include_in_menu: false on every schema node that appears in the custom menu, to prevent duplicate sidebar entries (see rules/schema-integration.md)

   Include these as comments at the top of the file, before the --- document separator. This ensures the user sees the guidance alongside the menu definition.

Supporting References

• examples.md -- Four worked menu hierarchies (flat, grouped, generic-linked, full multi-domain) ready to copy and adapt
• infrahub-yml-reference.md -- .infrahub.yml project configuration
• common/rules/ -- Shared rules (git integration, caching gotchas) that apply across all skills
• managing-schemas -- Schema node kinds that menus link to
• rules/ -- Individual rules organized by category prefix