Skip to main content

Layout Priorities

When more than one layout's page-path rules could match a URL, priority decides which one wins. This page covers the semantics and practical strategies for setting priority values.

For the broader targeting model (Exact / Starts with / Contains / Ends with / Regex), see Layout targeting.

Why priorities matter​

Without priorities, overlapping page-path rules cause unpredictable behavior:

URL: /article/sports-news

Layout A — Starts with: /article/           → matches
Layout B — Starts with: /article/sports     → also matches

Which one wins? Priority decides.

How priorities work​

Layouts are checked in priority order (lower number = higher priority):

Priority 1   → checked first (most specific)
Priority 10  → checked second
Priority 50  → checked third
Priority 100 → checked last (fallback)

First match wins. Once a layout matches, lower-priority layouts are skipped.

Priority scale​

PriorityTypical use
1–5Very specific overrides
10–20Specific page types
50General page types
100Default fallback

Leave gaps between the numbers (10, 20, 30 rather than 1, 2, 3) so you can insert new priorities later without renumbering the existing set.

Example: news site​

LayoutPage-path rulesPriorityMatches
Breaking NewsStarts with: /breaking/1Breaking news (special ads)
Sports ArticlesStarts with: /article/ + key-value section = sports5Sports articles
Article PagesStarts with: /article/10All other articles
Category PagesStarts with: /category/20Category listings
HomepageExact: /20Homepage
DefaultRegex: .*100Everything else

URL: /article/football-game-recap with section = sports targeting:

  1. Breaking News (priority 1)? No match — path doesn't start with /breaking/
  2. Sports Articles (priority 5)? Match — this layout activates

Setting priority​

The priority field lives on the layout's main form alongside name and scope. Set it when creating or editing any layout:

  1. Inventory → Layouts → open the layout
  2. Set or change the Priority value (integer — lower = higher)
  3. Save
  4. Ship a release from Wrapper → Releases for the change to take effect

Priority strategies​

Section-based​

Group by site section with consistent priorities:

  • Priority 10 — content types
    • Starts with: /article/
    • Starts with: /video/
    • Starts with: /podcast/
  • Priority 20 — listing pages
    • Starts with: /category/
    • Starts with: /tag/
    • Starts with: /author/
  • Priority 100 — fallback
    • Regex: .*

Override-based​

Use low priorities for special cases:

  • Priority 1 — experiments / overrides
    • Starts with: /article/ + key-value experiment = new_layout
  • Priority 10 — standard layouts
    • Starts with: /article/
    • Starts with: /video/
  • Priority 100 — fallback
    • Regex: .*

Simple​

For sites with few page types:

  • Priority 10 — all specific layouts
    • Exact: / (homepage)
    • Starts with: /article/
    • Exact: /about
  • Priority 100 — fallback
    • Regex: .*

Troubleshooting priority​

Wrong layout matching​

Symptom: A generic layout matches instead of the specific one you expect.

Check:

  1. Does the specific layout have a higher priority (lower number) than the generic one?
  2. Does the specific layout's page-path rule actually match the URL? (See Layout targeting for how pattern types match.)
  3. Is the specific layout in the currently deployed release?

Typical fix:

Before:
Article Pages — Starts with: /article/ — priority 50
Default       — Regex:       .*        — priority 50  ← same priority

After:
Article Pages — Starts with: /article/ — priority 10  ← higher priority
Default       — Regex:       .*        — priority 100

Unpredictable matching​

Symptom: Different layouts match the same URL on different loads.

Cause: Two layouts with overlapping rules share the same priority.

Fix: Assign distinct priorities to overlapping patterns.

Reviewing priority across layouts​

The layout list (Inventory → Layouts) is a compact three-column table (Name, actions, Last Modified) — it doesn't show priority inline or let you sort by it. To review priorities across all your layouts:

  • Open each layout and note its priority, or
  • Ask the AI Assistant: "List all my layouts with their page-path rules and priorities."

If this becomes painful in practice, consider that you probably have too many layouts — most publishers do fine with 4–6 layouts covering their main page types plus a fallback.

Best practices​

Do​

  • Leave gaps in numbering (10, 20, 30) so you can insert later without renumbering
  • Always ship a fallback layout (Regex: .*, priority 100) so every page has a layout
  • Document priorities — a line in the release notes when shipping a new layout explains why it got the number it did
  • Test edge cases — URLs that could match multiple layouts

Don't​

  • Use the same priority on overlapping patterns — causes unpredictable matching
  • Skip the fallback — pages with no matched layout serve no ads
  • Churn priorities frequently — pick a scheme and stick with it

Common questions​

What if two layouts have the same priority?

Behavior is undefined — one will match, but you can't reliably predict which. Always give distinct priorities to overlapping patterns.

Can I use decimal priorities?

The priority field accepts integers. Use gaps between integer values for insertion room.

How do I insert a layout between existing priorities?

If you used gaps (10, 20, 30), just pick an unused value in between (15). If everything is contiguous (1, 2, 3), you'll need to renumber the existing layouts and ship a single release that covers the reshuffle.

Next​