> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedynamite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Read /start/capabilities before choosing an integration. Use the deployed server’s tools/list for current tool inputs.

# Recommendations

> Select articles from your content catalog.

Connect an RSS feed or WordPress catalog to show relevant stories in an approved layout.

## Configure a placement

1. Register the article template and body selector.
2. Add a recommendation target to the page.
3. Add an HTML variant with one `<!--dynamite:stories-->` marker.
4. Choose `contextual`, `personalized`, or `discovery` as its `editorialPolicy` when using reader-v1.

Dynamite fills the marker with real titles, images, and canonical links. It excludes the current article, read stories, and duplicate placements. Stale or insufficient inventory keeps the original.

Start with one shelf below the article. See the [publishing playbook](https://docs.usedynamite.com/industries/media.md) for measurement.

> [accordion] Source and target configuration
>
> The source uses `kind: 'wordpress-rss'`, a feed `path`, topics, refresh/staleness settings, an `articleSelector`, and `targetIds` for article-template placements. Optional `ranking: 'reader-v1'` enables article-first ranking; optional `catalog: 'wordpress'` adds a durable full catalog.
>
> Two editorial target shapes are supported:
>
> ```json theme={null}
> { "kind": "recommendations", "count": 3, "priority": 5 }
> ```
>
> ```json theme={null}
> { "kind": "order", "linkSelector": "a.story-link", "pinnedSelector": ".pinned" }
> ```
>
> These are the `editorial` property of a complete target, not standalone configurations. Recommendation targets use component mode; editorial order targets use order mode. They are distinct from the explicit native `order.items` mapping.

> [accordion] Templates and story selection
>
> A non-default recommendation variant contains exactly one `<!--dynamite:stories-->` marker in its inline HTML template. It cannot use `componentId` for that template. The adapter fills the marker with selected catalog stories, retaining original titles, image URLs and canonical destinations.
>
> Reader-v1 variants use `editorialPolicy: 'personalized'`, `'contextual'` or `'discovery'`. The current article supplies useful context on a first visit; a repeated-visit gate is not required. Topic-based configurations use `contentTag` from the source's approved topics instead.
>
> The server shortlists at most 16 candidates and adds story-choice slots to the same decision call. Selected catalog IDs are separate from layout variant IDs. Invalid or duplicated selections use deterministic ranking fallbacks. The browser validates available IDs, excludes current/read articles and reserves stories across placements in priority order.

> [accordion] Catalog storage and sync
>
> | Source | Storage / scope | Use |
> | - | - | - |
> | RSS and optional topic feeds | Bounded current feed cache | Recent stories |
> | `archive` | Up to 300 reviewed metadata records in config | Curated archive |
> | WordPress catalog | Durable snapshots and sync checkpoints outside the draft | Full archive and native taxonomy |
>
> WordPress sync uses the configured public origin and authenticated `startEditorialSync` / `editorialSyncStatus` procedures. It excludes protected posts and invalid/off-origin canonicals. Full imports reconcile before replacing the active snapshot. Incremental refresh uses a modification overlap; weekly full reconciliation detects deletions, so removal can lag until a full sync.
>
> The browser receives a bounded context catalog; editorial-v3 decisions rank the full durable catalog on the server and return selected/history metadata. Older feature versions have narrower behavior. A service update does not publish a customer's draft.

> [accordion] Reading signals and freshness
>
> Use `readingSelector` for a unique article-body container and `readingIgnoreSelector` for native promotions. Reading observations require visible content, focused/visible document and recent activity. They exclude inserted modules and marked ads.
>
> Progress is viewport progress through article blocks, not proof every word was read. Estimated completion combines reaching the end with sufficient observed reading time. Reader-v1 excludes future stories, unavailable images, current/read stories, duplicate placements and non-evergreen content older than 45 days. Evergreen classification is a recorded heuristic, not a claim of human review.
>
> Stale or insufficient inventory leaves the original. Recommendation replacements refuse recognizable pinned/advertising content. Automatic placement changes stop after visibility or interaction; explicit preview overrides are separate.

> [accordion] Optional commerce cards
>
> A reviewed commerce source can replace the final card of one multi-card discovery shelf with merchandise or a subscription, retaining article recommendations. It uses approved product handles and fresh availability metadata. The replacement is a deterministic browser rule, not an unconstrained model offer.
>
> Merchandise requires two distinct matching articles with at least 30 seconds of focused reading and 50% progress in 14 days; subscription eligibility requires five engaged articles across three UTC dates. The current article is excluded. The browser caps promotions at one per seven days, consumed on render, and suppresses them without usable storage. Real subscriber/purchase exclusions still require actual connected data. These rules do not establish cross-site Shopify identity.
>
> Source: [editorial schemas](https://github.com/ion-design/dynamite/blob/main/packages/adaptive/src/editorial-schema.ts), [server catalog/decisions](https://github.com/ion-design/dynamite/tree/main/packages/personalization-server/src/editorial), [browser ranking](https://github.com/ion-design/dynamite/blob/main/packages/adaptive/src/browser/reader-ranking.ts), [commerce](https://github.com/ion-design/dynamite/blob/main/packages/adaptive/src/browser/editorial-commerce.ts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.