apairon
491f495c66
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
195 lines
5.7 KiB
Markdown
195 lines
5.7 KiB
Markdown
---
|
|
name: nova-navigation-modeling
|
|
description: Model navigations with current tibi-admin-nova navigation features. Covers recursive trees, declaredTrees, singleton navigation slots, preview design, language-specific trees, and how navigation modeling fits website information architecture.
|
|
---
|
|
|
|
# nova-navigation-modeling
|
|
|
|
## When to use this skill
|
|
|
|
Use this skill when:
|
|
|
|
- Designing header, footer, service, or utility navigation for a website project
|
|
- Modeling recursive navigation trees in Nova
|
|
- Using `viewHint.navigation` with declared singleton trees
|
|
- Refactoring a flat or editor-unfriendly navigation structure
|
|
|
|
## Goal
|
|
|
|
The goal is to model navigation as a first-class website structure with current Nova support, not as an afterthought or a plain array field.
|
|
|
|
On this stack, navigation influences:
|
|
|
|
- editor workflow
|
|
- public rendering
|
|
- SSR completeness
|
|
- language structure
|
|
- information architecture
|
|
|
|
## Source of truth
|
|
|
|
Use these sources when implementing or reviewing navigation modeling:
|
|
|
|
- `tibi-admin-nova/docs/collection-config.md`
|
|
- `api/collections/navigation.yml`
|
|
- `frontend/src/App.svelte`
|
|
- the frontend navigation rendering surface
|
|
|
|
## Current Nova navigation capability
|
|
|
|
Nova supports navigation-aware collection rendering through `meta.viewHint.navigation`.
|
|
|
|
Important building blocks:
|
|
|
|
- `nodesField`
|
|
- `declaredTrees`
|
|
- singleton root identifiers
|
|
- recursive tree editing for the configured nodes field
|
|
|
|
This is more than a plain `object[]` form. Use it when the project actually has structured navigation trees.
|
|
|
|
## Recommended mental model
|
|
|
|
Model navigation by tree purpose, not by arbitrary document naming.
|
|
|
|
Typical trees:
|
|
|
|
- main/header navigation
|
|
- footer navigation
|
|
- service/navigation variants
|
|
- language-specific trees
|
|
|
|
Each tree should have a clear editorial purpose and runtime consumer.
|
|
|
|
## Declared trees and singleton slots
|
|
|
|
Use `declaredTrees` when the project has known required navigation trees.
|
|
|
|
This gives editors:
|
|
|
|
- visible expected navigation slots
|
|
- stable entry points even when a tree is not created yet
|
|
- clearer distinction between intended site structure and accidental extra entries
|
|
|
|
For website projects, this is usually better than asking editors to create free-form navigation documents manually.
|
|
|
|
## Language-specific navigation
|
|
|
|
If the website is multilingual, decide explicitly whether navigation is:
|
|
|
|
- shared across languages
|
|
- separate per language
|
|
- partially shared with localized labels
|
|
|
|
The starter's current navigation collection models separate declared trees per language and per type. That is a good default when localized slugs and labels differ.
|
|
|
|
## Node schema design
|
|
|
|
Each navigation node should represent an editorially meaningful choice.
|
|
|
|
Typical node fields:
|
|
|
|
- `name`
|
|
- internal page reference
|
|
- external toggle
|
|
- external URL
|
|
- hash/anchor
|
|
- nested child nodes
|
|
|
|
Keep the schema focused. Do not overload navigation nodes with unrelated layout or content concerns unless the runtime genuinely needs them.
|
|
|
|
## Preview design
|
|
|
|
Navigation authoring depends heavily on preview quality.
|
|
|
|
Use previews so editors can quickly tell:
|
|
|
|
- whether a node points to an internal page or external URL
|
|
- what label it displays
|
|
- which tree they are editing
|
|
|
|
The current starter navigation config already demonstrates a strong pattern: previewing internal page lookup data and external URLs differently.
|
|
|
|
## Depth and constraints
|
|
|
|
Set `maxLevel` intentionally per tree.
|
|
|
|
Examples:
|
|
|
|
- header navigation may allow two levels
|
|
- footer navigation may allow one level
|
|
- service navigation may have different limits
|
|
|
|
Depth is an information-architecture decision, not only a UI detail.
|
|
|
|
## Navigation and runtime
|
|
|
|
Navigation modeling must match the frontend and SSR expectations.
|
|
|
|
Important checks:
|
|
|
|
- the frontend knows which tree to load
|
|
- language/type keys are stable
|
|
- SSR loads navigation as page-critical shell data when needed
|
|
- internal page references remain readable in admin and resolvable in runtime
|
|
|
|
Do not design a navigation schema in admin that the frontend cannot consume cleanly.
|
|
|
|
## Recommended patterns
|
|
|
|
### Header/footer split
|
|
|
|
Recommended shape:
|
|
|
|
- separate tree purpose via singleton markers such as type/language
|
|
- separate max depth per tree
|
|
- stable declared trees for required site areas
|
|
|
|
### Internal/external mixed navigation
|
|
|
|
Recommended shape:
|
|
|
|
- explicit external toggle
|
|
- page foreign key for internal links
|
|
- external URL only when external is true
|
|
- preview that makes the choice obvious
|
|
|
|
### Multilingual navigation
|
|
|
|
Recommended shape:
|
|
|
|
- declared trees per language
|
|
- clear language field
|
|
- editor-visible grouping of the trees
|
|
|
|
## Anti-patterns
|
|
|
|
- One generic navigation document with no stable tree identity
|
|
- Weak previews that show only IDs or unclear node labels
|
|
- No explicit distinction between internal and external targets
|
|
- Unlimited nesting without an actual UX reason
|
|
- Admin tree design that does not match frontend loading/runtime rules
|
|
|
|
## Verification checklist
|
|
|
|
After changing navigation modeling, verify all of these:
|
|
|
|
1. Editors can find every intended navigation tree quickly.
|
|
2. Node previews make internal vs external links obvious.
|
|
3. Allowed depth matches the site structure.
|
|
4. Frontend loading still resolves the correct trees.
|
|
5. SSR still includes required navigation shell data.
|
|
6. `yarn validate` stays clean.
|
|
|
|
## What an LLM should inspect first
|
|
|
|
When asked to work on navigation in this starter, inspect in this order:
|
|
|
|
1. `api/collections/navigation.yml`
|
|
2. `tibi-admin-nova/docs/collection-config.md` section for `viewHint.navigation`
|
|
3. the frontend navigation loading/rendering path
|
|
4. SSR assumptions around header/footer shell data
|
|
5. the website's language and information-architecture requirements
|
|
|
|
This prevents navigation edits that are technically valid but editorially or runtime-wise incoherent.
|