Preview Scenarios

A scenario is a real-world surface your template appears in. In Local Template Preview, the toolbar lets you switch between scenarios, each pairing a host page with a placement config (the parameters passed to the production SDK's renderActions()).

allegro-preview ships three built-in scenarios:

Tab	Description
Standalone	Template rendered on its own in an isolated iframe
Article · Append	Template injected after the full content of a mock article
Article · Cut	Template injected after paragraph 3 of a mock article using the truncate placement method

Custom Scenarios

Define your own scenarios to preview templates inside the real surfaces of your site — a paywalled article, a homepage rail, a newsletter shell. Create an .allegro-preview/ folder at the root of your templates directory, with one subfolder per scenario:

.allegro-preview/
├── paywalled-article/
│   ├── scenario.json     # required: name + placement config
│   ├── host.html         # optional: your mock host page markup
│   └── host.css          # optional: host page styles
└── homepage-rail/
    ├── scenario.json
    └── host.html

Each scenario.json mirrors the production SDK's placement parameters:

{
  "name": "Paywalled Article",
  "target_selector": "#article-body",
  "placement_method": "truncate",
  "truncation_unit": "paragraphs",
  "truncation_count": 4,
  "truncation_style": "cut"
}

Key	Required	Notes
name	Yes	Label shown on the scenario tab.
target_selector	When host.html is present	CSS selector in your host page to inject into.
placement_method	When injecting	truncate or append.
truncation_unit	When truncate	e.g. paragraphs.
truncation_count	When truncate	Whole number.
truncation_style	When truncate	e.g. cut.

How the host page is chosen:

• With host.html — your markup is the page, and the template is injected into target_selector using placement_method. host.css is included automatically.
• Without host.html — the template renders standalone, and target_selector is ignored.

Custom scenarios appear as additional tabs alongside the built-in ones and live-reload when you edit them.

Example: a custom host page

A scenario is a folder of up to three files. The host.html file is the full page your template is injected into — it is plain HTML, styled with host.css, with behavior added through an inline <script> (there is no separate host.js file; host-page JavaScript lives inside host.html).

.allegro-preview/paywalled-article/scenario.json:

{
  "name": "Paywalled Article",
  "target_selector": "#article-body",
  "placement_method": "truncate",
  "truncation_unit": "paragraphs",
  "truncation_count": 4,
  "truncation_style": "cut"
}

.allegro-preview/paywalled-article/host.html:

<article class="post">
  <h1>The Future of Local News</h1>
  <p class="byline">By Jordan Ellison · March 14, 2026</p>

  <div id="article-body">
    <p>The city council voted unanimously Tuesday to approve a sweeping new transit plan.</p>
    <p>Mayor Ellison called the decision a turning point for how the region gets around.</p>
    <p>The plan upgrades 14 bus lines and adds three new light-rail corridors downtown.</p>
    <p>Critics warn the projected cost may climb once land acquisition is factored in.</p>
  </div>

  <script>
    // Host-page JS runs in the preview exactly as it would on your real site —
    // useful for mimicking a paywall, lazy-loaded content, or analytics hooks.
    const body = document.getElementById('article-body');
    body.querySelectorAll('p').forEach((p, index) => {
      p.dataset.paragraph = String(index + 1);
    });
    console.log(`[host] article rendered with ${body.children.length} paragraphs`);
  </script>
</article>

.allegro-preview/paywalled-article/host.css:

.post {
  max-width: 680px;
  margin: 0 auto;
  padding: 32px 24px;
  font-family: Georgia, serif;
  line-height: 1.7;
}

.post .byline {
  color: #6b7280;
  font-family: system-ui, sans-serif;
  font-size: 0.85rem;
}

With this scenario.json, the template is injected into #article-body using the truncate method after the fourth paragraph — reproducing how it appears mid-article on your site, including any host-page scripts and styles.

note

The .allegro-preview/ folder is ignored by the GitHub template sync — it never becomes a template and never produces a sync warning. Keep your scenarios in your repo without affecting what syncs to Allegro.