Skip to content

ADR 0009 — Instagram reel highlight: link-out cards in the new theme + showcase, no embed, no API

Status: Accepted Date: 2026-05-09 (revised same-day to narrow scope to new-theme stack) Decision-makers: Administrator (pre-formation); ratified by Communications Committee once seated

Context

The Guild operates an active Instagram channel and wants to highlight a featured reel on its public surfaces.

The Guild is mid-migration off the current production stack on ganjierguild.com (WordPress + YOOtheme Pro) onto a new theme + plugin stack (guildcommerce-theme + guildcommerce-core) which is currently being staged for go-live. Repeated attempts to wire YOOtheme Pro's native Instagram element on the existing production site have failed. The pattern matches a well-known operational pain point: Meta's Instagram Basic Display API has been progressively restricted for third-party plugin use, and YOOtheme's element (along with most WordPress Instagram-feed plugins) depends on tokens that either require business-verification flows the Guild does not yet meet or that silently expire and break without notice.

Given the migration is in flight, the Administrator has scoped the Instagram highlight to the new stack only. The current production ganjierguild.com will be replaced when staging goes live; investing in the legacy YOOtheme integration is wasted work.

In-scope surfaces for this ADR:

  • guildcommerce-theme — the new WordPress theme being staged to replace YOOtheme on ganjierguild.com
  • guildcommerce.pplx.app — React/Vite static showcase

Explicitly out of scope (deferred or dropped):

  • Current production ganjierguild.com running YOOtheme Pro (will be replaced; not worth wiring)
  • The MkDocs document library at ginalyncox.github.io/ganjier-guild-launch-blueprint/ (deferred — no current need to surface marketing content there; document library readers are operators and counsel, not prospects)

A solution that depends on Instagram's API auth chain is a solution that fails the same way on a different timeline. A solution that depends on Instagram's embed <blockquote> script works today but adds 100+ KB of third-party JavaScript per surface and will break the moment Meta changes the embed contract.

Options considered

  1. Native YOOtheme Pro Instagram element + Basic Display API token
  2. Pros: native to YOOtheme, designed for this; auto-pulls latest reels.

  3. Cons: depends on a Meta token chain that has been brittle for months; only useful on a stack the Guild is actively replacing; same failure on every surface it's deployed to.

  4. Instagram official <blockquote> embed

  5. Pros: shows the reel inline; no API auth required; works on any HTML surface.

  6. Cons: ~100 KB+ of Meta-controlled JavaScript per page; every layout change Meta ships could break the rendered card; conflicts with the Guild's privacy-conscious posture (third-party tracking on every page that loads the embed); slow on mobile.

  7. Thumbnail-card linkout (a Guild-controlled image + caption + button → Instagram URL)

  8. Pros: zero third-party runtime; identical implementation works on the new WP theme and on the React showcase; survives every Meta API/embed change; page-weight is one image; easy to template and re-skin per surface; matches the Guild brand cascade.

  9. Cons: doesn't auto-update; the operator has to refresh the thumbnail and URL when a new reel is featured.

  10. Auto-pulling RSS-to-static via a backend job

  11. Pros: auto-updating without depending on Meta's client-side runtime.
  12. Cons: still depends on the same Meta auth chain, just moved server-side; introduces a new component to operate; failure mode is "stale card silently for weeks." Same root issue dressed differently.

Decision

Adopt Option 3: thumbnail-card linkout, manually curated, deployed identically on the two in-scope surfaces:

  • The new guildcommerce-theme (replaces YOOtheme on ganjierguild.com when staging goes live)
  • The guildcommerce.pplx.app showcase

Each surface gets a small "Featured reel" component with:

  • A static thumbnail image (Guild-controlled, served from the Guild's own assets; no Instagram CDN dependency)
  • 1–2 lines of caption (also Guild-controlled, not pulled from Instagram)
  • A primary button: "Watch on Instagram →" linking to the specific reel URL
  • A secondary link: "More on Instagram" linking to the channel

The featured reel is refreshed manually by the Communications Committee (or the Administrator pre-formation) using the curation cadence in marketing/instagram-highlight-spec.md.

Instagram's <blockquote> embed is not used on any Guild surface. No Meta API token is configured anywhere in the new stack.

Consequences

Positive:

  • One implementation pattern works identically across the new WP theme and the React/Vite showcase.
  • No dependency on any Meta API token, embed script, or auth flow that can break without warning.
  • Page weight per surface is one image plus the existing CSS; no third-party JavaScript runtime, no third-party tracking pixels added by the embed.
  • The Guild controls the visual presentation entirely — thumbnail, caption, and call-to-action all sit inside the brand cascade.
  • The Communications Committee gets a single editable artifact (the curation step) instead of a token-management chore.
  • The current production YOOtheme integration is left alone — it will be replaced wholesale when staging goes live, so investing in it now would be wasted work.

Negative / trade-offs accepted:

  • The featured reel does not update automatically. If nobody refreshes it, the card sits on the same reel until someone does. The curation cadence in the spec mitigates this with a 2-week refresh target and a quarterly committee review.
  • Visitors click out to Instagram instead of viewing inline. We accept this because the alternative is page-weight + tracking + brittleness.
  • The thumbnail must be re-exported in the right brand dimensions each time. The spec includes the dimensions and an export checklist so this stays a 5-minute task, not a design exercise.
  • Until staging goes live, prospects landing on the current ganjierguild.com won't see a featured reel. Acceptable: staging go-live is the priority, and the existing site is not being actively iterated.

Follow-up actions:

  1. Author the build spec (marketing/instagram-highlight-spec.md) covering the new-theme + showcase implementations.
  2. Implement the showcase card on guildcommerce.pplx.app as part of the next showcase deploy (Full-stack Dev).
  3. Build the theme template part / block in guildcommerce-theme so it ships with staging (Full-stack Dev). The component is dormant on staging until first curation.
  4. First curation (thumbnail + caption + reel URL) lands as part of staging go-live, OR is left empty until the Communications Committee is seated — operator's call at go-live time.
  5. Add the curation step to the Communications Committee monthly cadence (see programs/community/README.md cadence table — the committee owns AMA programming and now owns the reel refresh).
  6. Once the founding board is seated and the social-media policy is adopted, this ADR is reviewed alongside that policy and reaffirmed or amended.
  7. If the document library (ginalyncox.github.io/ganjier-guild-launch-blueprint/) ever needs a featured-reel surface, this ADR is amended rather than re-decided.

References