> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Working with Reusable Content
> How Gradial detects, edits, and governs reusable content blocks and structured content items across platforms.
Most enterprise platforms share a common pattern: some content lives directly on a page, and some is managed centrally and surfaces in many places at once. This second category — reusable content — requires extra care, because a change at the source propagates to every page or asset that references it.
This page covers how Gradial identifies and handles reusable content, what operations are supported, rules you can configure, and governance best practices.
***
## Two Types of Reusable Content
Reusable content across all supported platforms falls into two broad categories.
Content **and** presentation bundled together — a header, footer, promo banner, or CTA section rendered as a complete visual unit. One change affects every page it appears on.
Content **only**, with no layout attached — a set of fields (headline, body, image reference, metadata) consumed and rendered independently by each channel or page.
| | Layout-based block | Structured content item |
| -------------- | -------------------------------- | ------------------------------------ |
| **AEM** | Experience Fragment (XF) | Content Fragment (CF) |
| **Sitecore** | Partial Design | Datasource item |
| **Contentful** | Referenced Entry (layout-driven) | Entry (data source) |
| **Marketo** | Snippet, shared template module | Token, custom object |
| **SFMC** | Content Block | AMPscript snippet, data-driven block |
***
## How Gradial Identifies Reusable Content
You don't need to know whether content lives directly on a page or inside a reusable block. **Gradial detects this automatically.**
When you describe a change — "update the headline in the hero section" — Gradial inspects the page, determines whether that content is sourced from a reusable item, and surfaces that information before applying any changes.
| Scenario | Gradial behavior |
| ------------------------------------------------- | --------------------------------------------------------------------------- |
| Content lives directly on the page | Change is applied to the page |
| Content is sourced from a layout-based block | Gradial identifies the block and applies the change there |
| Content is sourced from a structured content item | Gradial identifies the item and applies the change to the appropriate field |
This means you can point Gradial at a page URL and describe what you want changed — Gradial figures out where to make the edit.
***
## What Gradial Can Do
* **Edit** — Update text, links, images, or field values inside an existing block or item
* **Copy** — Duplicate a reusable block or structured item to create a new variant
* **Move** — Relocate a reusable item to a different folder, path, or location in your content hierarchy
* **List** — Surface all instances where a reusable item is referenced, so you know the blast radius before making a change
* **Replace or reorder** — Swap a component within a layout block, reorder sections, or remove an element
* **Create new** — Build a new reusable block or structured item from a Figma file, Word doc, or URL
* **Place on a page** — Reference a new or updated item from a specific page or set of pages
***
## Safe by Default
Gradial's default behavior when editing reusable content is to **create a launch or variation** rather than modifying the original directly. This means:
* **No unintended propagation** — The original stays unchanged until you explicitly approve and publish
* **Review before it goes live** — Changes can be validated in a staged environment first
* **Rollback capability** — The original version is preserved if changes need to be reverted
Reusable content changes propagate to every page or asset that references the source item. Before running, use Gradial's **List** capability to confirm which pages are affected.
***
## Rules: Simplifying Fragment Management
Gradial allows you to configure rules that reduce the technical knowledge business users need to work with reusable content. Instead of knowing which content model to use, which fields map to which components, or which items require elevated review — users describe what they want, and rules handle the rest.
### Model / Template Selection
**Problem:** Users shouldn't need to know which content model or template to use for different content types.
**Solution:** Rules that automatically select the correct model based on the type of content being created or updated.
| Rule example | Behavior |
| ----------------------------- | ------------------------------------------------------------ |
| "Product description" content | Gradial automatically uses the Product content model |
| FAQ content | Routes to the FAQ model, ensuring consistent field structure |
| Legal disclaimer | Uses the Legal content model and flags for compliance review |
### Naming Conventions
**Problem:** Inconsistent naming makes reusable content hard to find, audit, and govern over time.
**Solution:** Rules that enforce naming patterns automatically when Gradial creates or copies items.
| Content type | Generated name pattern |
| --------------------- | ---------------------------------------------- |
| Product content items | `[product-line]-[product-name]-[content-type]` |
| Campaign blocks | `[campaign-id]-[region]-[component]` |
| Layout blocks | `[site]-[section]-[variant]` |
### Field Mapping
**Problem:** Business users don't know which fields in a content model map to which visible elements on a page.
**Solution:** Rules that translate natural language intent to specific field names.
| User says | Maps to |
| ------------------------ | ---------------------------------------------- |
| "Update the headline" | `fragment.title` field |
| "Change the description" | `fragment.bodyText` field |
| "Update the CTA" | `fragment.ctaText` + `fragment.ctaLink` fields |
### Governance Warnings
**Problem:** Some reusable items require extra review, but users don't always know which ones.
**Solution:** Rules that surface warnings when high-impact items are being modified — without blocking the workflow.
| Rule trigger | Warning shown |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Any item in the `legal-*` namespace | "This content contains legal copy — ensure compliance review before publishing" |
| Site-wide layout blocks (header, footer) | "This block appears across the entire site — verify with the governance team before promoting" |
| Items referenced in more than 20 pages | "This item is referenced in \[N] pages — use List to review impact before running" |
***
## Governance Best Practices
Fragment changes can have wide downstream impact. Establishing clear ownership before you scale Gradial usage on reusable content prevents surprises.
### Ownership by content type
| Content type | Suggested governance |
| --------------------------------------------- | ------------------------------------------------------ |
| Site-wide layout blocks (header, footer, nav) | Senior stakeholder or web governance approval required |
| Campaign-specific blocks | Marketing team ownership with standard review |
| Legal / compliance content | Legal review required before any change |
| Localized variants | Regional team approval plus global oversight |
### Versioning and documentation
* Maintain a changelog for high-impact reusable items
* Document the reason for each significant change
* Set review dates for time-sensitive content (e.g., seasonal promotions)
* Use Gradial's Work Log as your audit trail for agent-made changes
### Cross-team coordination
* Set up notification workflows when changes to shared items are proposed
* Use staging environments to validate impact before promoting
* For high-traffic items, schedule update windows during low-traffic periods
***
## Nesting: The Three-Layer Rule
Reusable content items can reference other reusable items, creating nested structures. While this enables flexibility, excessive nesting creates real problems: slower page rendering, difficult debugging, unpredictable update cascades, and author confusion about where content actually lives.
**Best practice: limit nesting to three layers maximum.**
```
Page
└── Layout block (Layer 1)
└── Structured content item (Layer 2)
└── Nested structured content item (Layer 3) ← MAXIMUM
```
**Signs you've over-nested:**
* Authors can't determine where content originates
* Small changes require tracing through multiple items
* Page previews don't match expectations
* Performance degrades on content-heavy pages
**How to simplify:**
1. Audit the full dependency tree for deep structures
2. Flatten items that are always used together — combine them into one
3. Accept intentional duplication when it's clearer than deep nesting
4. Document any nesting that remains, and why it's necessary
***
## Setting Up Rules in Gradial
Work with your Gradial administrator to configure rules for your environment:
List all content models, templates, and structured item types across your platform and their intended purposes.
Establish naming patterns for each content type — by team, campaign, region, or component type.
Identify how your business users naturally describe content elements, and map those phrases to the underlying field names.
Determine which items require elevated review and define the warning conditions that should surface for them.
Codify the three-layer rule in your team guidelines and configure Gradial to flag structures that exceed it.
***
## Platform Details
Select your platform for targeting conventions, terminology, and tips specific to your environment.
AEM has two distinct types of reusable content. Gradial detects which is in use automatically, but knowing the difference helps you write better prompts and understand impact.
### Experience Fragments (XFs)
Layout-based reusable blocks — components, design, and content bundled together. Stored at `/content/experience-fragments/`. Best for: headers, footers, promotional banners, navigation blocks.
**Gradial behavior:**
* Detects XF usage automatically when you target a page
* Creates a Launch or variation by default — does not edit the original directly
* XFs can have **variations** (e.g., "Web," "Email") — specify which if relevant
* Copy and Move operations respect the XF folder structure
**Targeting tips:**
* XF paths: `/content/experience-fragments/{site}/{locale}/{fragment-name}`
* To list all pages using an XF, ask Gradial to list references before editing
* After editing, preview on multiple representative pages before promoting the Launch
**Example prompts:**
```
Update the promo banner Experience Fragment at
/content/experience-fragments/acme/us/en/promo-banner.
Change the headline to "Experience the future of AI content automation."
List which pages use this XF before making any changes.
---
On the homepage at example.com/home, update the promotional
banner section — change the headline and remove the secondary CTA.
(Gradial will detect the XF automatically.)
---
Copy the Q3 Campaign Experience Fragment and rename it
Q4 Campaign. Update the headline and CTA for the new campaign.
```
***
### Content Fragments (CFs)
Structured content items — fields and data, no layout. Stored in the DAM at `/content/dam/`. Best for: product descriptions, author bios, FAQs, legal disclaimers. May feed web, email, app, and API consumers simultaneously.
**Gradial behavior:**
* Detects CF usage automatically when you target a page
* Creates a variation rather than editing the master by default
* Move and Copy operations preserve CF model associations
* Field mapping rules translate natural language to specific CF fields
**Targeting tips:**
* CF paths: `/content/dam/{project}/{folder}/{fragment-name}`
* Specify the field name when possible ("update the 'bodyText' field")
* Always check headless consumers — CFs may feed more than web pages
* List references before editing to understand full downstream impact
**Example prompts:**
```
In the 'Product Benefits' Content Fragment at
/content/dam/acme/fragments/product-benefits,
update the 'benefitsList' field — change the second bullet
to reflect the new pricing.
---
List all pages and channels that reference the 'Legal Disclaimer'
Content Fragment at /content/dam/acme/legal/disclaimer before
making any changes.
---
Move the seasonal-promo Content Fragment from
/content/dam/acme/campaigns/q3 to /content/dam/acme/campaigns/q4
and update the headline field.
```
Sitecore separates layout reuse from content reuse. Gradial detects which is in use when you target a page, but knowing the distinction helps with targeting precision.
### Partial Designs
Layout-based reusable blocks (SXA) — a named set of components and datasources applied to pages via Page Designs. Best for: headers, footers, shared promotional sections.
**Gradial behavior:**
* Detects Partial Design usage when you target a page and describe a shared section
* Edits are staged before publishing; must be published from the Partial Designs builder
* Copy creates a new named Partial Design; Move updates its location in the design hierarchy
**Targeting tips:**
* Specify by name: "the Global Header Partial Design"
* Confirm which Page Designs include this Partial Design before running
* List which pages use the design before making structural changes
**Example prompts:**
```
In the Global Header Partial Design, update the primary CTA
from "Request Demo" to "Get Started" and update the link to /get-started.
---
List all pages that use the Promotional Banner Partial Design
before I make changes to it.
---
Copy the Q3 Promo Partial Design and rename it Q4 Promo.
Update the headline and background image.
```
***
### Datasource Items
Content tree items that components point to for their data, stored separately from the page. Can be shared (affects many pages) or local (affects only one page).
**Gradial behavior:**
* Detects datasource items automatically when you target a page component
* Distinguishes shared vs. local datasources and surfaces this before editing
* Move operations update the datasource path reference in all components using it
* List shows all components and pages referencing a shared datasource
**Targeting tips:**
* Shared datasources: often at `/sitecore/content/{site-collection}/{site}/Data/`
* Specify the template field name when updating (e.g., "the 'Headline' field")
* Always confirm shared vs. local status before running — ask Gradial to list references first
**Example prompts:**
```
On the /platform page, update the hero component headline
to "The operating system for modern marketing."
(Gradial will detect whether the datasource is shared or local.)
---
List all pages that reference the hero datasource item at
/sitecore/content/acme/home/Data/Hero before editing it.
---
Move the shared CTA datasource from /sitecore/content/acme/Data/CTAs/Q3
to /sitecore/content/acme/Data/CTAs/Q4 and update the link field.
```
Contentful's model is entirely Entry-based. Whether an Entry is "reusable" depends on how many other Entries or pages reference it via Reference fields.
**Gradial behavior:**
* Detects Entry references when you target a page — surfaces how many other pages use the same Entry
* Saves changes as Drafts; explicit publish required
* Copy creates a new Entry with the same content model; Move updates folder/path organization
* List shows all Entries and pages referencing a given Entry
**Targeting tips:**
* Entry IDs are the most reliable targeting method (stable regardless of name changes)
* Find Entry IDs in the Contentful app URL: `app.contentful.com/spaces/{space}/entries/{entry-id}`
* Specify the field name for structured updates ("update the 'legalDisclaimer' field")
* Use the References panel in Contentful or ask Gradial to list references before editing
**Example prompts:**
```
Update Entry ID abc123def. Change the 'headline' field to
"AI-powered content operations for enterprise teams."
First, list how many pages reference this Entry.
---
On the page at example.com/solutions, update the hero banner.
Change the headline and CTA — do not change the background
image Entry reference.
(Gradial will identify the Entry automatically.)
---
Copy the Q3 Hero Banner Entry and create a Q4 version.
Update the headline and CTA fields for the new campaign.
```
Marketo's reusable content is oriented around email and landing page assets.
### Snippets
Centrally managed HTML content placed into emails and landing pages. Updating and re-approving a Snippet propagates to every asset using it.
**Gradial behavior:**
* Creates a draft version before editing if the Snippet is currently approved
* List shows all emails and landing pages using a Snippet
* Copy creates a new Snippet; Move updates its Design Studio location
* After editing, affected assets must be re-approved in Marketo
**Example prompts:**
```
List all emails using the "Q3 Legal Footer" Snippet,
then update the disclaimer text with the version
in the attached document.
---
Copy the Q3 Promotional Snippet and create a Q4 version.
Update the headline and offer details.
---
Move the "Legal Disclaimers" Snippet folder from
Design Studio/Q3 to Design Studio/Archive/Q3.
```
***
### Tokens
Program-scoped variable content (`{{my.headline}}`) inherited by all assets within a program.
**Gradial behavior:**
* Token changes apply to all assets in the program immediately
* List shows all assets in the program that use a given token
* Always specify the program name when targeting
**Example prompts:**
```
In the Q3 Launch Campaign program, list all assets using
{{my.heroHeadline}}, then update the token value to
"Automate your content operations — from brief to live."
```
SFMC's reusable content lives in **Content Builder**, oriented around email and journey assets.
### Content Blocks
Named, centrally stored blocks referenced across multiple emails. Changes render on next preview or send — no separate publish step. Gradial saves a new version rather than overwriting.
**Gradial behavior:**
* Detects Content Block usage when you target an email and describe a shared section
* Copy creates a new Content Block; Move updates its Content Builder folder location
* List shows all emails referencing a Content Block
* For journey-based emails, Gradial edits the content asset — re-activation in Journey Builder stays with your team
**Targeting tips:**
* Reference by name and folder path: "the 'Q3 Legal Footer' block in Compliance/Footers"
* Organize Content Builder into clearly named folders — it makes targeting significantly more reliable
* For blocks in active journeys, coordinate timing carefully — changes render on next execution
**Example prompts:**
```
List all emails using the "Q3 Legal Footer" Content Block
in the Compliance/Footers folder, then update the
disclaimer text with the attached version.
---
In the email "Campaign Q3 Master," update the hero block.
Change the headline to "The future of content operations is here."
(Gradial will identify the Content Block automatically.)
---
Copy the "Q3 Hero Block" from Campaign/Q3 and move it to
Campaign/Q4. Update the headline and CTA link.
```
***