Navigation and Menus

karaoke-cms automatically generates default navigation menus from your active modules — no configuration required. If you want to customize the structure, add entries, create submenus, or define a footer menu, create _website/menus.yaml in your vault.

Default menus

When menus.yaml is absent, karaoke-cms generates:

• main — a horizontal header nav with entries for Blog, Docs, Tags, and Search, based on which modules are active
• footer — a horizontal footer nav with an RSS link

menus.yaml location

your-vault/
  karaoke-cms/
    config/
      menus.yaml   ← create this file to customize menus

Basic structure

menus:
  main:
    orientation: horizontal
    entries:
      - id: blog
        text: Blog
        href: /blog
        weight: 10
      - id: docs
        text: Docs
        href: /docs
        weight: 20
  footer:
    orientation: horizontal
    entries:
      - text: RSS
        href: /rss.xml
        weight: 10

menus is a map of named menus. main renders in the site header; footer renders in the site footer. You can define additional named menus and render them with the <Menu name="..." /> component.

Entry fields

Field	Description
id	Unique identifier — required when other entries reference this entry via parent:
text	Link label
href	Link destination
weight	Sort order — lower numbers appear earlier
parent	Id of the root-level entry to nest this under (single-level only)
static	Renders a non-interactive text label — no link, no href
when	Visibility condition — hides the entry when the condition is not met
entries	Inline child entries (alternative to parent: on individual entries)

Weight

Entries are sorted by weight in ascending order. Assign weights in increments of 10 (10, 20, 30…) so you have room to insert entries later without renumbering.

Orientation

orientation: horizontal or orientation: vertical. Themes use this to style the menu appropriately for its placement.

Submenus

There are two ways to create submenus.

Option 1: inline entries — nest children directly under the parent entry:

entries:
  - id: docs
    text: Docs
    href: /docs
    weight: 20
    entries:
      - text: Getting Started
        href: /docs/getting-started
      - text: API Reference
        href: /api-docs

Option 2: parent: reference — declare the child entry separately and point it at a root entry by id:

entries:
  - id: docs
    text: Docs
    href: /docs
    weight: 20
  - text: API Reference
    href: /api-docs
    parent: docs

Both produce the same result. Use entries: when the children are tightly related to their parent; use parent: when you want to keep entries flat and compose later. Submenus are single-level only — nesting beyond one level is not supported.

Visibility conditions

Use when: collection:name to hide an entry when a collection is disabled or has no published posts. This keeps the nav clean when a module is turned off:

entries:
  - id: blog
    text: Blog
    href: /blog
    weight: 10
    when: collection:blog
  - id: docs
    text: Docs
    href: /docs
    weight: 20
    when: collection:docs

Omit when to always show the entry regardless of collection state.

Static labels

Use static: to render a non-interactive text separator or section heading inside a menu. Static entries have no href and are not clickable:

entries:
  - static: "More about this site"
    weight: 10
  - text: About
    href: /about
    weight: 20

Complete example

menus:
  main:
    orientation: horizontal
    entries:
      - id: blog
        text: Blog
        href: /blog
        weight: 10
        when: collection:blog
      - id: docs
        text: Docs
        href: /docs
        weight: 20
        when: collection:docs
        entries:
          - text: Getting Started
            href: /docs/getting-started
          - text: API Reference
            href: /api-docs
            when: collection:api-docs
      - id: search
        text: Search
        href: /search
        weight: 50

  footer:
    orientation: vertical
    entries:
      - text: RSS
        href: /rss.xml
        weight: 10
      - static: "Resources"
        weight: 20
      - text: Tags
        href: /tags
        weight: 30
        when: collection:blog