Skip to main content

URLs & Page Overlays

How OQO resolves URLs, what "parents" are, and how pages can override posts and collections.

Flat Slugs, Deep URLs​

Every piece of content on your site gets a unique slug. Posts, collections, and blogs share a single slug namespace -- no two can have the same slug. Pages live in their own namespace and can intentionally reuse a slug to override content.

The interesting part: content can appear at any depth in the URL hierarchy.

/about                                    --> Page
/food                                     --> Collection
/best-pizza-recipe                        --> Post
/food/best-pizza-recipe                   --> Same post, with "Food" as parent
/italy/food/pizza/best-pizza-recipe       --> Same post, deeper context
/travel-blog                              --> Blog
/travel-blog/my-trip-to-rome              --> Post in "Travel Blog"
/tags/italian                             --> Tag listing

The slug best-pizza-recipe always points to the same post. The segments before it (italy/food/pizza) provide context -- they become the "parents" of the content.

Parents​

When a URL has multiple segments, OQO resolves each one independently. The last segment is the content being displayed. Everything before it becomes the parents -- an ordered chain of context.

URL: /italy/food/pizza/best-margherita

Parents:  Italy (Collection) → Food (Collection) → Pizza (Collection)
Content:  Best Margherita (Post)

Parents are useful for:

  • Breadcrumb navigation -- Home / Italy / Food / Pizza / Best Margherita
  • Contextual navigation -- "More from this collection" links
  • Conditional styling -- show different layouts depending on the parent

For a URL like /best-margherita (no parents), the post renders exactly the same way -- it just won't have breadcrumb context.

System Pages Are Templates​

This is the key insight: the five system pages (Home, Post, Tag, Collection, Blog) are not traditional web pages with their own URLs. They are display templates that define how each content type looks on your site.

When someone visits /best-margherita:

  1. OQO resolves the slug to a Post
  2. OQO finds the Post system page (the template)
  3. The template's sections render with the post's data injected

The Post system page defines the layout -- which sections appear, in what order, with what settings. The actual content comes from the post itself.

┌─────────────────────────────────────────┐
│         Nav Section (from layout)       │  ← Same on every page
├─────────────────────────────────────────┤
│                                         │
│     Post Template Sections              │  ← Defined on the Post system page
│     (hero, article body, tags,          │
│      related posts, comments...)        │
│                                         │
│     Data comes from the actual post:    │
│     title, content, cover image,        │
│     author, tags, etc.                  │
│                                         │
├─────────────────────────────────────────┤
│         Footer Section (from layout)    │  ← Same on every page
└─────────────────────────────────────────┘

This means you control how posts look by editing the Post system page's sections. You control what posts say in the blogger editor.

The same pattern applies to collections, tags, and blogs -- each has a system page template that you can customize with sections, and the actual data comes from the content being viewed.

Page Overlays​

Here's where it gets powerful. Regular pages can override posts and collections by using the same slug.

How It Works​

Say you have a post called "Shopping in New York" with the slug shopping-in-new-york. Normally, visiting /shopping-in-new-york renders that post using the Post system page template.

Now imagine it's the holiday season. You want to give this post a special treatment -- a festive layout, extra seasonal sections, curated gift guide links alongside the article. You create a page called "Shopping in New York" with the same slug: shopping-in-new-york.

When that page is published:

  • /shopping-in-new-york renders the page (with your holiday layout and sections)
  • The original post still exists, untouched

When you unpublish the page after the holidays:

  • /shopping-in-new-york goes back to rendering the post via the standard Post template
  • No URLs changed, no content was modified

Priority​

URL resolution follows a strict priority:

PriorityTypeWhen It Applies
1stPublished PageA non-system page with this slug exists and is published
2ndCollectionA collection has this slug
3rdPostA post has this slug

When to Use Page Overlays​

  • Seasonal campaigns -- holiday-themed landing pages that temporarily replace standard content
  • Featured content -- give an important post a custom layout with extra sections
  • A/B testing layouts -- try a different section arrangement for specific content
  • Promotional pages -- wrap existing content with CTAs, banners, or partner sections

Admin Visibility​

When you create a page that shares a slug with existing content, the admin panel shows a notice:

"This page overrides post 'Shopping in New York' when published"

This makes it clear that publishing the page will change what visitors see at that URL.

Blog-Prefixed URLs​

Posts that belong to a blog automatically include the blog's slug as a prefix:

Post without a blog:  /best-pizza-recipe
Post in "Food Blog":  /food-blog/best-pizza-recipe

This happens automatically -- you don't need to configure anything. The blog prefix creates natural content grouping in your URLs while keeping individual post slugs unique.

Tags Use a Special Route​

Unlike posts, pages, and collections, tags don't participate in the cascading URL system. They have a dedicated /tags/ prefix:

/tags/technology
/tags/culture
/tags/events

This keeps tag URLs predictable and separate from your content hierarchy.

Next Steps​