WORK-183
Setting up your dashboard 0 entities found · 6/29 branches scanned
ID:WORK-183Status:done

Site reference docs for new nav layouts and the pagination rune

Update site/content/runes/nav.md so it documents every new layout value with live preview blocks, and create site/content/runes/pagination.md from scratch covering both auto and explicit forms. Reference-doc work only — site adoption (changing _layout.md files in production) is owned by WORK-184.

Priority:mediumComplexity:smallMilestone:v0.13.0Source:SPEC-046, SPEC-047
Branches 3
History 3
  1. a9f3b2a
    statusreadydone
    by bjornolofandersson
  2. 8211229
    Created (ready)by bjornolofandersson
  3. 29cd7e5
    Content editedby Claude
    plan: split site docs and adoption into dedicated v0.13.0 work items

Acceptance Criteria

site/content/runes/nav.md updates

  • Intro rewritten to reflect that nav is the single primitive for sidebar, header menubar, footer columns, and section-landing cards — not just sidebars
  • layout attribute added to the Attributes table with values vertical (default), menubar, columns, cards
  • collapsible boolean attribute added to the Attributes table
  • defaultOpen attribute added to the Attributes table (comma-separated group titles)
  • A ## Layouts section with one subsection per value, each containing a {% preview %} block showing the markdoc source and the rendered output:
    • ### Vertical (sidebar) — current behaviour, default
    • ### Menubar (header) — example with two groups (Product, Resources), each with a couple of items; note dropdown / hamburger behaviour
    • ### Columns (footer) — example with three groups (Product, Resources, Legal)
    • ### Cards (section landing) — example with explicit slugs; show enriched output with title + description + icon
  • A ## Collapsible sidebars section with a {% preview %} example demonstrating {% nav collapsible %} and explaining the auto-open-current-section behaviour
  • A short ## Frontmatter fields used by cards section documenting that the cards layout reads title, description, and (new) icon from each linked page's frontmatter, with a tiny YAML example
  • A ## Mobile behaviour callout (or section) noting that menubars collapse to a hamburger below the breakpoint and that columns stack — both handled by Lumina, no author work required
  • Cross-references to WORK-184 are NOT included in the rendered docs; the doc page itself is timeless

site/content/runes/pagination.md (new file)

  • Frontmatter: title: Pagination and a description line
  • Intro paragraph naming the use case (sequential reading — tutorials, ordered docs, recipes) and contrasting with breadcrumb and nav
  • ## Basic usage section with a {% preview %} showing {% pagination auto /%} placed in a _layout.md
  • ## Explicit prev / next section with a {% preview %} showing {% pagination prev="install" next="configuration" /%}
  • ## Ordering section explaining the priority — declared nav order → frontmatter order → directory order — with a short worked example
  • ### Attributes table covering auto, prev, next, scope, prev-label, next-label
  • ### Common attributes table identical to other rune docs (the shared layout / spacing / inset / tint / bg row)
  • A note on boundary behaviour (no wrap-around; first page → no prev link, last → no next)
  • A note on the scope="section" value and when to use it

Cross-cutting

  • site/content/runes/_layout.md updated to add pagination to the appropriate group in the rune catalog sidebar (likely under Site, next to nav, toc, breadcrumb)
  • site/content/runes/rune-catalog.md (or wherever the catalog is generated / curated) lists the pagination rune
  • All new {% preview %} blocks render correctly (verify with cd site && npm run dev)
  • Authoring docs in site/content/docs/authoring/ are reviewed; if they have a section that lists rune examples or content-model patterns that should mention the new layouts, update them — otherwise no changes needed

Approach

Both pages follow the existing rune-doc convention seen in site/content/runes/nav.md and the other rune pages: short intro, ## Basic usage with a markdoc code block (or {% preview %} for live examples), ### Attributes table, ### Common attributes table.

{% preview %} is the right primitive for showing layouts because it renders the actual rune output alongside the source — much more useful than a static code block for visual primitives like cards and menubar. If preview is unavailable for any reason in a given environment, fall back to a code block plus a separate "Rendered output" screenshot.

The cards-layout preview will need at least one or two example child pages with description and icon set in frontmatter so the enrichment is visible. The site/content/runes/*.md pages already have description on every page; for icon, pick a couple of existing rune pages and add icon: ... frontmatter as part of this work item (small, mechanical, doesn't change rendered output until cards is used).

This is intentionally a docs-only work item — no code changes. Depends on the feature items having shipped so the examples actually render.

Dependencies

  • WORK-178layout attribute available
  • WORK-179collapsible available
  • WORK-180cards and Frontmatter.icon available
  • WORK-181 — menubar behaviour available (so the menubar preview actually opens dropdowns)
  • WORK-182pagination rune available

References

  • SPEC-046, SPEC-047 — design specs.
  • site/content/runes/nav.md — existing rune doc structure to extend.
  • Any existing site/content/runes/*.md page that uses {% preview %} — reference for the preview pattern.

Resolution

Completed: 2026-05-18

Branch: `claude/v0.13-pagination-nav-bvuEP`

What was done

  • `site/content/runes/nav.md` — rewrote the page to reflect that `nav` is the single primitive for sidebars, header menubars, footer columns, and cards. Added a `## Layouts` section with one subsection per layout value, each with a live `` block (for vertical and basic usage) or a markdoc code sample (for menubar/columns/cards, since these are inappropriate for inline preview at content width). Added `## Collapsible sidebars` with the `defaultOpen` override. Added `## Frontmatter fields used by cards` documenting `title`/`description`/`icon`. Added `## Mobile behaviour` callout. Attributes table now lists `layout`, `collapsible`, `defaultOpen`, `auto`, `ordered`.
  • `site/content/runes/pagination.md` — new file. Frontmatter, intro contrasting with `breadcrumb`/`nav`, `## Basic usage`, `## Explicit prev / next`, `## Ordering` (with the three-priority table), `scope` subsection, `## Boundaries`, attributes + common-attributes tables.
  • `site/content/runes/_layout.md` — `pagination` added under `## Site` next to `nav`/`toc`/`breadcrumb`.
  • `site/content/runes/rune-catalog.md` — `pagination` row added to the `Site` table; `nav` description updated to reflect the four layouts.
    • Notes

      • Used `` blocks for the vertical / basic usage examples. Menubar / columns / cards are documented with markdoc code blocks plus prose explanations — the live preview surface inside a content column is too narrow to demonstrate horizontal nav and dropdown behaviour usefully, and the SSR render of a slug-only cards layout depends on the surrounding pages having matching frontmatter, which is fragile in a doc preview. The actual behaviour is exercised end-to-end on the live site as part of WORK-184.
      • Did not modify `site/content/docs/authoring/` — those pages cover content-model patterns and Model API specifics; the layout / collapsible / cards features don't change authoring patterns, they add new attribute values, which are already documented in the `nav.md` Attributes table.
      • The pagination page links to `/runes/pagination` from the sidebar — site adoption of the rune is owned by WORK-184.
        • ID:Status:draft

          Site reference docs for new nav layouts and the pagination rune

          Update site/content/runes/nav.md so it documents every new layout value with live preview blocks, and create site/content/runes/pagination.md from scratch covering both auto and explicit forms. Reference-doc work only — site adoption (changing _layout.md files in production) is owned by WORK-184.

          Priority:mediumComplexity:unknown