Navigation implementation

Menu behaviour, Markdown directives and responsive rendering are described in the canonical navigation reference. Browser steps live in the menu guide. Keep those pages aligned when changing menu metadata or generated output.

Markdown directives

The directive syntax is portable between sites. Upload and download must translate between parent URLs and stable page IDs without changing the page's content unexpectedly.

Storage and API

Both HTML and Markdown pages store the same optional JSON field:

{
  "menu": {
    "visible": true,
    "position": 1,
    "parentId": "the-parent-pages-id"
  }
}

This field is included in full pages and page summaries, project snapshots and the source revision used by publication. An absent field has the legacy defaults. An omitted menu on a page update preserves existing menu settings. When supplied, menu is a complete object with visible and position; parentId is optional. The API resolves Markdown parent URLs to page IDs when saving. IDs keep the menu relationship intact when a parent URL changes. A downloaded file uses a URL because page IDs differ between installations. When a request contains both menu and leading directives, supplied directive values override the corresponding JSON values; omitted directives keep those JSON values.

Use the existing POST /api/pages, PUT /api/pages/{id} and POST /api/content/render endpoints. Render requests may include the current page id, title, path and menu to preview unsaved changes in navigation. The same tree is rendered for previews, the editor decoration and immutable releases.

Themes and responsive behaviour

A Navigation binding emits the same generated tree in preview, editor decoration and publication. Render native details/summary disclosures, current-page aria-current, and keyboard-accessible desktop/mobile alternatives. Neutral .viking-navigation, .viking-nav-list, .viking-nav-item, .viking-nav-toggle and .viking-nav-submenu styling precedes theme CSS. Decoration stays outside the editable page document. New menu features are tracked in TODO.md.