Navigation & relationships

This is where most of a site build’s logic lives, and where the mesh’s model is least obvious. The package ships the traversal as feed functions — breadcrumbs, hubMembers, relatedLinks, labelForSlug, and the entities/facet reader — so most of this is a call, not code you write. Three things still trip people up; get them right and the rest is mechanical.

1. A page’s entity key is not its URL slug

A category page at /categories/rotary-lobe-pumps (plural, a URL) has entity key rotary-lobe-pump (singular, an identity). The mapping is the graph’s DERIVED entityOf — never the URL segment. A naive match of a slug segment against entity keys returns nothing.

const g = loadGraph();
const node = g.bySlug("/categories/rotary-lobe-pumps")!;
g.entityOf(node.id);      // "rotary-lobe-pump"  ← the identity
// pages that resolve to this entity:
g.byLabel("page").filter((n) => g.entityOf(n.id) === g.entityOf(node.id));

Whenever you need “the thing this page is about,” read entityOf(id). The slug is for routing; the entity is for relationships.

2. Membership is two different mechanisms

“What belongs under this hub” has two answers depending on the relationship, and they come from two different places. This is the single biggest source of “where does this come from” in a mesh build.

Belongs-to → the mesh link tree (derived)

A category’s products, a manufacturer’s models — the members of a hub — are the inverse of the up-links. hubMembers returns them as ready-to-render cards (label, slug, thumbnail), sorted, pruned to the render set:

const g = loadGraph();
hubMembers(g, "/categories/rotary-lobe-pumps", { status: renderableStatuses(env) });
// → PageSummary[] — the pages that link up to this hub

Under the hood that’s the derived down edge (the reverse of the view’s up in site.manifest.json). For the topical members of a hub’s owned topic, use the graph directly: g.membersOf(hubId). See The mesh & links for how up-links are derived in the first place.

Facets → the entities table (a project-declared relationship)

A product’s industries, applications, collections — its facets — are a different kind of relationship: many-to-many attributes of an entity, not a hub it funnels into. These are not in the up-link mesh at all. They are facet memberships your project declares under taxonomy.facets (carried as facet props on the entity nodes in the graph). A facet hub’s up-links are empty; its membership is “every entity whose facet column contains this value” — which is entitiesByFacet:

const entities = loadEntities();
 
// the members of a facet hub (every product serving an industry):
entitiesByFacet(entities, "industry", "dewatering");   // → Entity[]
 
// the facets OF one entity (for its chips/attributes):
entityFacets(entityBySlug(entities, "rotary-lobe-pump", ENTITY_KEY)!, FACET_AXES);
// → { industry: ["dewatering", "hvac"], application: [...] }

3. Labels live in the bundle, not the graph

The committed graph carries a page’s slug but not its display name. Editorial meta — navTitle, title, metaDescription — lives in the page’s content bundle (content/<slug>/index.yaml), because meta is split: the engine owns identity, the writer owns editorial copy. So labelling a related slug means resolving that target’s card. The page-summary projection does this once and indexes it:

const g = loadGraph();
labelForSlug(g, "/categories/rotary-lobe-pumps");
// → "Rotary Lobe Pumps"  (navTitle ?? title ?? humanised slug)
 
// or the whole card — label, description, thumbnail — for a tile:
const card = pageSummary(g, slug);    // { label, description, thumbnail, … }
 
// build the full index up front for a large build:
const cards = pageSummaries(g, { status: renderableStatuses(env), thumbnails: THUMBNAILS });

Thumbnails are config-driven: pass { thumbnails: THUMBNAILS } and each card carries a normalized thumbnail ({ asset, alt?, caption?, ratio? }) resolved from the bundle path your mesh declares (site.thumbnail, content.thumbnail by default, per-page-type overridable). asset is the bare co-located filename — resolve its URL with assetUrl(slug, asset).

Reading the link fields

The link tree lives in site.manifest.json, one entry per page — read it with loadManifest().pages[slug] (the feed helpers wrap this, so you rarely read it directly). Each entry carries the derived edges (snake-cased on disk). What each means, and when to use it from an SSG:

Each page carries a link block per view — live (published-only, for prod) and preview (writing/review/published, for local/dev) — and each block resolves the same four scopes. A build runs in one view, so you set it once and read links without branching:

// set the view once (from your env) — every page.links.* is then that view's links
const pages = loadPages({ view: viewForEnv(env) });
pages[0].links.up;       // the up-links for THIS build — no live/preview logic in your templates
pages[0].links.siblings; // …and siblings / across

The feed helpers (breadcrumbs, hubMembers, relatedLinks) do the same under the hood, so you rarely read loadManifest().pages[slug] directly.

Breadcrumbs & related links

A breadcrumb is the path from an apex hub down to the page. breadcrumbs walks the primary up-link chain and returns each hop as a card, root → page:

const g = loadGraph();
breadcrumbs(g, slug).map((c) => ({ href: c.slug, label: c.label }));
 
// "related" / "see also" rails — siblings (shared domain axis) + across (cross-axis):
const { siblings, across } = relatedLinks(g, slug, { status: renderableStatuses(env) });

breadcrumbs follows the preview view’s up-links (the widest structural path — it exists before every hub publishes); with opts.status it stops climbing at the first non-renderable ancestor, so a production crumb never links to a hidden hub.

Related

• Build a website — the overview
• Publish status & environments — prune edges to non-rendered targets
• The mesh & links — how up-links, siblings, and dual parents are derived
• How the pieces fit — why meta is split and where each fact lives
• Content-types package — the full reader API