menus.yaml Reference

File location: {vault}/_website/menus.yaml

If this file is absent, karaoke-cms generates default main and footer menus from your active modules. Define this file to customise or extend them.

Top-level structure

menus:
  <menu-name>:
    orientation: horizontal | vertical
    entries:
      - ...

Multiple named menus are supported. The main and footer names are used by the default theme.

Field	Type	Required	Description
`orientation`	`'horizontal' \| 'vertical'`	No	Layout direction. Default: `'horizontal'`.
`entries`	`MenuEntryConfig[]`	No	List of entries. Sorted by `weight` ascending.

Entry fields

Field	Type	Required	Description
`id`	`string`	No	Unique identifier. Required when other entries reference this entry via `parent:`.
`text`	`string`	No	Link label text. Ignored when `static` is set.
`href`	`string`	No	Link destination URL. Ignored when `static` is set.
`weight`	`number`	No	Sort order — lower numbers appear first.
`parent`	`string`	No	Id of a root-level entry to nest this entry under as a submenu item. Single-level only. Falls back to root with a warning if the referenced id is not found.
`static`	`string`	No	Renders a non-interactive text label — no link, no href. When set, `text` and `href` are ignored.
`when`	`string`	No	Visibility condition. See Visibility conditions.
`entries`	`MenuEntryConfig[]`	No	Inline child entries. Alternative to using `parent:` on individual entries.

Visibility conditions

Only one condition syntax is supported:

Syntax	Behaviour
`collection:name`	Hides the entry when the named collection is disabled or has no published content. Omit `when` to always show.

Examples:

when: collection:blog      # hide if blog is disabled or empty
when: collection:docs      # hide if docs is disabled or empty
when: collection:karaoke-cms  # hide when karaoke-cms handbook is not active

Named menus

`main`

Used by the theme for the primary site navigation. When absent from menus.yaml, karaoke-cms generates a default main menu from active modules in modules[] order (Blog weight 10, docs sections weight 20, Tags weight 30, Search weight 90).

`footer`

Used by the theme for the footer navigation. When absent, karaoke-cms generates a default footer menu with an RSS link.

Full schema example

# {vault}/_website/menus.yaml

menus:
  main:
    orientation: horizontal
    entries:

      # Basic link entry
      - id: blog
        text: Blog
        href: /blog
        weight: 10
        when: collection:blog   # hide if blog is disabled or empty

      # Parent entry (has children)
      - id: docs
        text: Docs
        href: /docs
        weight: 20
        when: collection:docs

      # Child entry — nested under 'docs' via parent:
      - id: api-docs
        text: API Reference
        href: /api-docs
        weight: 10
        parent: docs            # nests under the entry with id: docs
        when: collection:api-docs

      # Static label — non-interactive section divider
      - static: "Resources"
        weight: 80

      # Entry with inline children (alternative to parent: on child entries)
      - id: search
        text: Search
        href: /search
        weight: 90
        entries:
          - text: Tags
            href: /tags
            weight: 10

  footer:
    orientation: vertical
    entries:
      - text: RSS
        href: /rss.xml
        weight: 10

      # Static label in footer
      - static: "More about Karaoke"
        weight: 20

      - text: Manual
        href: /karaoke-cms/manual
        weight: 30
        when: collection:karaoke-cms

Submenu behaviour

A ▼ triangle indicator is rendered beside any entry that has child entries.
Hover opens the submenu (horizontal menus).
Click pins the submenu open; clicking outside or pressing Escape closes it.
Submenus are single-level only — child entries cannot themselves have children.