Manage shared content blocks

Note

Shared content blocks let you author content once and attach it to multiple sites within the same tenant. Common use cases: a standard FAQ used across every storefront in a tenant; a flash-sale HotDeal banner reused on the home page and a campaign landing page; an EarlyBird offer block shared between booking flows.

Outcome: a tenant Library populated with reusable blocks, attached to one or more SiteDefinitions' page compositions.

Time: ~5 minutes per block. Permission: Manager role on the tenant with Sites permissions (Sites.View / .Create / .Edit / .Delete).

Before you start

You need:

• A tenant with at least one published SiteDefinition (otherwise blocks have nothing to attach to). See configure a new site.
• Content ready: FAQ Q&A pairs, HotDeal copy + image URL + expiry, EarlyBird dates + items.

Block kinds

Four kinds ship in v1. Each has its own typed editor:

Kind	Use case	Notes
FAQ	Frequently asked questions, accordion-style.	HTML allowed in answers (sanitized server-side).
HotDeal	Single hero promotion card with countdown.	Optional expiresAt shows a countdown timer.
EarlyBird	Dated promotion (book early, travel later) with item list.	validFrom / validTo form the travel window.
Reviews	Disabled in v1 — placeholder rendered.	Activates when the Reviews module ships. Configuration is preserved.

A block is tenant-scoped — blocks created on Tenant A can't be attached to a site on Tenant B.

Step 1 — Open the Library

1. In the left sidebar, expand Site Forge and click Library.

2. The page opens at /apps/siteforge/library. You'll see:

   • A kind filter chip strip at the top (All / Reviews / FAQ / HotDeal / EarlyBird).
   • A row of New {kind} buttons.
   • A table of existing blocks with columns: Name, Kind, Active, Attached (count of sections using this block).

Step 2 — Create a new block

Click one of the New {kind} buttons (e.g., New FAQ). The page navigates to the editor at /apps/siteforge/library/new?kind=FAQ.

The editor has:

• Left column (8 of 12 cols) — the form fields.
• Right column (4 of 12 cols) — empty when creating; the "Where used" panel populates after the block is saved.

Common fields for every kind:

Field	Notes
Name	Admin-facing label, shown in the Library list.
Active	Inactive blocks don't appear in the per-site picker.

Below those, the kind-specific editor renders.

Step 3a — Fill the FAQ editor

Field	Notes
Title	Section title above the accordion (e.g. "Frequently asked questions").
Subtitle	Optional small text below the title.
Layout	accordion (collapsible) or list (always-open).
Items	List of {Question, Answer} rows.

For each item:

• Question — Plain text, max 400 chars.
• Answer — HTML allowed. Tags whitelisted: p, strong, em, ul, ol, li, a, br. Anything outside the whitelist is stripped on save.

Warning

The HTML sanitizer is strict — it strips style attributes, scripts, images, and most tags. If you paste rich text from Word or Google Docs, expect formatting to flatten. For richer formatting, edit the answer markup directly using the allowed tags.

Click + Add item to append a row, the trash icon to remove.

Step 3b — Fill the HotDeal editor

Field	Notes
Title	The headline of the deal card (e.g. "Tết flash sale — 30% off").
Subtitle	Optional supporting copy.
CTA label	Button text (e.g. "Shop the deal").
CTA URL	Where the button links. Relative path or absolute URL.
Image URL	Hero image for the card. Leave blank to render text-only.
Expires at (UTC)	Optional. When set in the future, a countdown timer renders. Leave empty to disable countdown.
Linked item	Optional — Type (product / tour / category / url) + Id or Url. Used by analytics.

Tip

The countdown counts down to the Expires at instant in the user's local timezone. Set this to your campaign's hard end so the deal auto-expires from the public site.

Step 3c — Fill the EarlyBird editor

Field	Notes
Title	Headline (e.g. "Early-bird Spring 2026").
Subtitle	Supporting copy.
Discount label	Short badge text (e.g. "Save 25%").
CTA label / URL	Button text + link.
Early bird ends at	When the booking discount window closes. Shows as "Book by ..." on the public site.
Travel valid from / to	The travel date window. Shows as "Travel ..." on the public site.
Items	List of {Type, Id, ImageUrl, Headline} cards. Type is product or tour; the Id references that record.

The items render as a 3-column card grid below the title. Leave the items list empty to render a "title + dates + CTA" only.

Step 3d — Reviews editor (disabled in v1)

The Reviews editor renders an info banner explaining the block ships disabled in v1. You can still set:

• Title / Subtitle — Used as the placeholder banner header.
• Mode — auto (filter) or manual (id list). Saved for future use.
• Layout — carousel or grid. Saved for future use.

The block renders an info banner ("Reviews not yet enabled for this tenant") on the public site until the Reviews module ships.

Step 4 — Save

Click Save at the bottom of the editor card. The page navigates back to the Library list. Your new block appears with Attached: 0.

Note

Validation runs server-side. If a required field is missing or the HTML in a FAQ answer is malformed, you'll see an error toast — fix and re-save.

Step 5 — Attach the block to a site

A block sitting in the Library doesn't appear on any public site until you attach it to a SiteDefinition's home composition.

1. Open the target site at Site Forge → Sites → {your site}.

2. Click the Page Sections tab.

3. Click + Add section.

4. Pick the matching Section key from the dropdown (FAQ, HotDeal, EarlyBird, or Reviews).

5. The Shared block dropdown unlocks. Pick the block you just created from the list of blocks of that kind.

6. Set Order to position the section where you want it on the home page (lower numbers = higher up).

7. Leave Enabled on.

8. Click Save.

The next time the site renders (within ~60 s of save, FusionCache TTL), the section appears at the configured position.

Tip

The same block can be attached to multiple sites for the same tenant. Edit the block once, all attached sites pick up the change after their cache expires. The Library page shows the Attached count next to each block — 3 means it's attached to three SitePageSection rows across the tenant.

Step 6 — Manage existing blocks

The Library list supports:

• Edit — click the block name or the pencil icon. Opens the same editor pre-filled with the existing payload.
• Where used — the editor's right column lists every SitePageSection this block is attached to, with site name + page key + position. Click a site name to jump to its config page.
• Delete — the trash icon. Disabled when the block is attached to one or more sections. To delete a block, first detach it from every site that uses it.

Warning

Editing a block changes the content on every site it's attached to. If you need a per-site variant, create a new block and attach it there instead. The Library deliberately doesn't fork — that would defeat the "edit once, propagate" design.

Why is delete disabled?

The Attached count gates deletion. The button is enabled only when the count is zero. To delete:

1. Open every site listed in the editor's "Where used" panel.
2. Remove the section row that points at the block (delete the row, not the block).
3. Save the site.
4. Return to the Library — the count now shows 0, delete is enabled.

This prevents orphaning sections (which would render an empty placeholder).

Step 7 — Filter by kind

The kind-filter chip strip at the top of the Library list narrows the table to one kind at a time. Useful when you have a lot of blocks — click FAQ to see only FAQ blocks, All to see everything.

The chip-row order (All / Reviews / FAQ / HotDeal / EarlyBird) matches the SharedContentBlockKind enum order.

Permissions reference

Action	Policy required
View Library + open editor	Permissions.Sites.View
Create a block	Permissions.Sites.Create
Edit a block	Permissions.Sites.Edit
Delete a block	Permissions.Sites.Delete

(Same family as the Sites permissions — Library is part of the Site Forge surface.)

What's next?

• Configure a new site — if you haven't created a SiteDefinition yet, do that first; the Library has nothing to attach to without one.
• Reuse across templates — the four shared blocks render on any template that calls UseSharedBlocks() during startup. Both v1 templates (NorthStar, TravelAgent) opt in, so blocks Just Work across e-commerce and travel sites.