Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

content-sdk-navigation-component

/content-sdk-navigation-component

Pomaga zbudować nawigację na stronie opartej na Sitecore: z drzewa treści czy z listy linków, z pułapkami, które psują nawigację.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
05.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 05.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Pomaga zbudować nawigację na stronie opartej na Sitecore: z drzewa treści czy z listy linków, z pułapkami, które psują nawigację.

Oryginalny opis (EN)

Decides how to build navigation on a Sitecore head app: derived from the content tree vs an authored link list, plus the traps that make nav fail silently. Use when adding a site nav, jump bar, footer links or breadcrumb.

Jak działa

  1. The decision, first
  2. Derived navigation
  3. Authored navigation
  4. Do not fetch instead of fields — the trap that survives every gate
  5. Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 137 linii, 1 303 słów
Podgląd SKILL.md
---
name: content-sdk-navigation-component
description: "Decides how to build navigation on a Sitecore head app: derived from the content tree vs an authored link list, plus the traps that make nav fail silently. Use when adding a site nav, jump bar, footer links or breadcrumb."
license: Apache-2.0
compatibility: "SitecoreAI. Content SDK head apps (App Router and Pages Router). Derived from a one-pager build and two multi-page brands on one SitecoreAI estate, 2026-08-28; the list-component leg corrected 2026-09-18 to match content-sdk-list-component 1.2."
metadata:
  author: hahn-solo
  version: "1.3.1"
---

# Sitecore Navigation Components

## The decision, first

Navigation looks like one problem and is two. **The markup is nearly identical; the data source is not.**

| Question | Shape |
|---|---|
| Should the nav change when someone adds a page? | **Derived.** Walk the content tree. |
| Is this a curated set of destinations an editor decides? | **Authored.** A list of link items. |
| One page, jumping to sections on it? | **Authored**, with anchor links. A derived nav has nothing to walk. |

**Default to two renderings, not one with a mode switch.** They share a presentation layer and
nothing else — different fields, different fetch, different failure modes, different editor
experience. One rendering that branches on a parameter has to satisfy both contracts at once, and
the trap in § "Do not fetch instead of `fields`" is exactly where that goes wrong.

Use **one rendering with a `Source` rendering parameter** only when you genuinely need an author to
flip an existing placement between modes without re-placing it. That is rarer than it sounds.

**Both on one page is normal and correct** — a derived site nav in the header, an authored section
jump-bar under it. They are different renderings doing different jobs, not a duplication.

---

## Derived navigation

Walks the tree from a root, to a bounded depth, through a filter.

### `rootPath` is the SITE node, not Home

The single most common mistake. The site item and the home page are different items — point at the
site node and append `/Home` (or whichever child is the actual home) to get the level you mean.
Aiming at the site node and rendering its children gives you *Home, Data, Media, Settings*, i.e.
the site's plumbing in the navigation bar.

### Bound the depth explicitly — Edge degrades SILENTLY

**Sitecore Edge has a query depth budget, and exceeding it does not error.** It returns a truncated
result. A three-level nav built against a small tree works, ships, and then quietly loses its third
level when the tree grows — with a green build, a 200, and no console warning.

So: state the depth as an explicit number (a rendering parameter or a field), never "walk all
children". And when you test it, **test against a tree deeper than the one you designed for** — a
nav that is correct on a 6-page site proves nothing about a 200-page one.

### Filter deliberately

A `Navigation Filters` item (the SXA-shaped hook) or an explicit "show in navigation" checkbox on
the page template. Without one, every scaffolding page — `Components Preview`, test pages, staging
drafts — appears in the public nav the moment someone creates it. That is a content-authoring
accident waiting to happen, not a hypothetical.

### The stock headless Navigation resolver: set its parameters, know its limits

Measured on SitecoreAI preview, 2026-10-29. With only the variant (`FieldNames`) on the placement, the
stock Navigation rendering returns level 1 below Home, no children, hidden pages included. Its
headless parameters template shows no navigation fields, yet the resolver reads SXA's Foundation
ones from the placement: `Filter` (a Navigation Filter item: Main / Sidebar / Breadcrumb Navigation),
`LevelFrom` and `LevelTo` (items under `Navigation/Enums/Navigation Level`), `NavigationRoot`,
`Flattened`, `AddRoot`. With a filter and levels set it drops filtered pages, nests `Children` and
marks the context page `active`; `LevelFrom` = `LevelTo` = 2 is a section menu of the current
level-1 ancestor. Every entry carries only `Id`, `Href`, `NavigationTitle`, `Styles`, `Querystring`.

Two things it cannot do: expand only the active trail (it returns the full level range for every
branch), and list an item whose template does not derive from `_Navigable`. A "link in the menu"
item (an external URL at a position in the tree) is skipped, and even on `_Navigable` it would get
its own URL, not the link. A menu that needs either keeps its own walk (component-level GraphQL),
reading the stock `NavigationFilter` so hiding a page still works the stock way.

---

## Authored navigation

A curated list of links. **This is a list component** — an author must be able to *add a row*, not
merely re-point rows that already exist.

**Load `content-sdk-list-component` and follow it.** The short version: a Multilist alone is the
wrong shape, because it only lets an author choose among items that already exist. You need a
container template that carries **`_HorizonDatasourceGrouping`** as a base template (that is what
gives Pages its **Items** section, i.e. the "add a link" affordance), an element template, insert
options via the container's `__Standard Values.__Masters` (which only decides *which* template a new
row uses), and a **branch** as the rendering's Datasource Template. The four legs fail
independently — an earlier version of this paragraph credited `__Masters` with the Pages affordance,
and that was wrong: a template can carry `__Masters` and still give an author no way to add a row.

### In-page anchors (the one-pager case)

Each link item carries a General Link field whose **`linktype` is `anchor`**, with the target
section id as the anchor value. Two things to get right:

- The target `id` must exist in the rendered DOM. Assert it — an anchor pointing at a section that
  was renamed scrolls nowhere and returns HTTP 200 while doing it.
- **Never write `href={link?.value?.href || '/'}`.** A fail-open fallback turns a missing link into
  a silent dead link that every crawler and every smoke test reports as fine. Render nothing, or
  render the item unlinked, but do not invent a destination.

---

## Do not fetch instead of `fields` — the trap that survives every gate

The authorability trap in its purest shape — a component that renders perfectly and cannot be
edited — and navigation is where it bites hardest.

A derived nav is fetched, so it is tempting to fetch the authored one too — or to write one
component that fetches in both modes. **`ComponentQuery` REPLACES the entire `fields` payload.** A
component whose data arrives that way has no `fields` for the editor to click, so it renders
perfectly and cannot be edited in Pages. That is how a previous build shipped 17 of 21 renderings
un-editable past 704 tests, 88 e2e tests and four reviews.

The rule is narrow and worth stating precisely: **"derive your TYPES from the SDK's `.d.ts`" is a
rule about typing what you fetch. It does not license fetching instead of `fields`.**

- **Authored nav:** every link arrives on `fields` and renders through an SDK field component.
- **Derived nav:** the *tree walk* is a fetch, necessarily — but any authored chrome on the same
  rendering (a heading, a CTA) still arrives on `fields`. Do not let the fetch swallow the
  authorable parts.

Verify by opening the Pages canvas and clicking the thing. `audit-component-authorability.mjs` is a
floor: it cannot tell whether the fields a component renders are the *right* ones.

---

## Checklist

- [ ] Decided **derived vs authored** from the data source, not from how it looks.
- [ ] Two renderings unless an author genuinely needs to flip modes in place.
- [ ] Derived: `rootPath` resolves to the **site node**, with the home child appended.
- [ ] Derived: depth is an **explicit bound**, and was tested against a deeper tree than designed for.
- [ ] Derived: a filter exists, so scaffolding pages cannot appear in the public nav.
- [ ] Authored: built as a **list component** (`content-sdk-list-component`) — an author can ADD a row.
- [ ] Anchors: `linktype: anchor`, and every target id asserted present in the DOM.
- [ ] **No fail-open `|| '/'` href anywhere.**
- [ ] Authored values arrive on `fields`, not via a `ComponentQuery` that replaces the payload.
- [ ] Opened Pages and edited one link by hand. The audit is a floor, not proof.

Wersje

W bazie nie ma innych skilli o nazwie content-sdk-navigation-component.

Migawka bazy z 13.11.2026 · wersja paczki edb6908fa662 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100content-sdk-app-router-component-level-navigation
    Buduje nawigację przez GraphQL na poziomie komponentu w aplikacji Content SDK: serwer pobiera wyższe poziomy, a klient dociąga głębsze.
  • 100content-sdk-feature-planner
    Zamienia zgłoszenie funkcji dla aplikacji Content SDK w plan blueprintu Sitecore: strona, komponent, ustawienie, model treści i dane.
  • 100content-sdk-pages-router-component-registration
    Rejestruje komponenty w wygenerowanym pliku .sitecore/component-map.ts aplikacji Pages Router Content SDK, bez ręcznej edycji mapy.
  • 100content-sdk-pages-router-component-scaffold
    Tworzy nowy komponent Sitecore w aplikacji Content SDK Pages Router: układ plików, interfejs właściwości i wpis w mapie komponentów.
  • 95breadcrumb-generator
    Dodaje, optymalizuje i audytuje nawigację okruszkową (breadcrumbs) na stronie, w tym znaczniki BreadcrumbList i SEO.
  • 100navigation
    Obejmuje nawigację w aplikacjach na Androida i Kotlin Multiplatform/iOS, w tym Navigation Compose, Navigation 3, trasy typowane, grafy zagnieżdżone i deep linki.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.