The One Template That Broke the Internet (And My Heart)

I fell in love with folder mapping when it solved an impossible problem: serving 5,000+ dynamic stock pages with one elegant template. No more managing thousands of individual pages. No more content duplication nightmares. Just pure operational efficiency—deploy changes instantly across your entire collection by modifying one file.

But folder mapping betrayed me. Google Search Console started reporting hundreds of phantom pages as valid content when they were actually errors. Search results displayed generic template titles instead of real content. Crawl budgets disappeared into soft 404 black holes. The solution I'd loved was systematically sabotaging the SEO performance it was meant to support.

Then I discovered something better. Content overlay with the API for Edge Delivery Services delivers folder mapping's promises without its compromises—pre-published dynamic pages that exist when they claim to exist, proper 404 responses for invalid requests, and search engines that can actually crawl and index your content correctly.

Keep reading if you want to learn from my mistakes and understand how we deprecate and replace folder mapping.

What Worked Well

We designed folder mapping to address a fundamental challenge in content management: efficiently serving thousands of pages without requiring authors to create physical pages and maintain each one individually. The solution was elegantly simple—use a single template that dynamically populated content at runtime based on URL paths.

Folder mapping did address immediate operational concerns. Authors no longer needed to create duplicate templates or manually manage thousands of similar pages. A financial website, for instance, could serve thousands of stock pages using one carefully crafted template that fetched real-time data for each requested stock symbol. The efficiency gains were substantial: content authors could deploy changes instantly across their entire dynamic page collection by modifying just one template, ensuring consistent design and reduced maintenance overhead.

These use cases are relevant and valid. The operational benefits folder mapping delivered were real and significant for teams managing large-scale dynamic content.

Where Folder Mapping Fell Short (And Why We're Deprecating It)

As implementations scaled in production environments, we discovered that the map is not the territory. Folder mapping's elegant conceptual model—one template serves all pages—broke down when it encountered the harsh realities of web architecture. The two critical failings emerged: phantom pages being classified as valid content by search engines, and search results displaying generic template titles instead of actual content.

Soft 404 Violations

When users accessed invalid URLs, the system would load the template successfully, then use client-side JavaScript to verify content existence. Invalid requests displayed 404 messaging but returned 200 OK status codes—a fundamental violation of HTTP protocol. At one customer site, Google Search Console reported over 400 phantom pages as valid content when they were actually error states.

Search Engine Confusion

Search results began displaying generic template titles like "Default" instead of dynamic content titles. Combined with soft 404 issues, this created a crawl budget efficiency problem—search engines consumed resources processing thousands of pages with incomplete content, leaving less capacity for indexing valuable pages.

The Stakes

These weren't minor technical inconveniences. They were actively sabotaging the SEO performance folder mapping was meant to support. Every soft 404 misled search engines about content availability. Every generic title reduced click-through rates from search results. The solution was systematically undermining the success of the sites it powered.

Moving On From Folder Mapping with Content Overlays

Folder mapping is now deprecated due to the fundamental SEO and architectural issues outlined above. The core problem was that folder mapping stitched content together at delivery time—every request triggered dynamic content generation, creating the soft 404 violations and search engine confusion that plagued implementations at scale.

Content overlays offer a better approach. Instead of stitching content at delivery time, content overlays combine content when previewing and publishing. This fundamental shift in timing eliminates the architectural compromises that made folder mapping problematic.

The benefits are substantial. Content overlays provide explicit preview and publish operations, giving authors control over when content becomes available. They leverage the solid content bus infrastructure for scalable delivery, ensuring consistent performance as implementations grow. Most importantly, they deliver reliable SEO results because content is delivered in the markup on the first fetch, with minimal impact on crawl budget.

Content overlays work through the Bring Your Own Markup (BYOM) concept, which allows external services to generate HTML markup directly for the content bus. When a user requests a page, the system delivers a proper 200 response for valid content or a legitimate 404 for non-existent pages. Search engines can crawl and index content correctly because the content actually exists when it claims to exist, with appropriate titles and metadata in place from the start.

Setting Up BYOM as Content Overlay

Ready to make the switch from folder mapping? The content overlay approach leverages the Bring Your Own Markup (BYOM) concept, which extends AEM's capabilities by allowing composition with external data sources. Since these dynamic pages don't exist in the primary content source, the overlay is activated to generate the markup for these pages.

Here's how to get started:

curl -X PUT https://admin.hlx.page/config/acme/sites/website.json \
  -H "content-type: application/json" \
  -H "auth-token: <your-auth-token>" \
  -d '{
    "data": {},
    "overlays": {},
    "source": {
      "overlays": [
        {
          "source": {
            "url": "https://acme.sharepoint.com/sites/new/SiteAssets/DocumentLibrary/website"
          },
          "content": {
            "source": {
              "url": "https://content-service.acme.com/data",
              "type": "markup"
            }
          }
        }
      ]
    }
  }'

Workflow

Once your site configuration is updated, the request flow works as follows:

Moving Forward

If you're currently using folder mapping, reach out to Adobe to discuss the deprecation timeline and migration path for your specific implementation. For teams facing similar large-scale dynamic content challenges, explore content overlays and BYOM as the architectural foundation for your solution—they deliver the operational efficiency of folder mapping without the SEO compromises.

Sometimes the solutions we love most are the ones that teach us the hardest lessons. Folder mapping seduced us with its elegant simplicity, betrayed us with its fundamental flaws, and ultimately led us to something better. That's the cycle of good engineering—falling in love with ideas, having them break your heart, and finding the wisdom to build solutions that won't betray the next person who falls for them.

P.S. For sites with thousands of pages, you can implement automation scripts to manage the publishing process. These scripts monitor data sources for additions and removals, automatically publishing or unpublishing pages while generating HTML markup on the fly. This maintains operational efficiency while ensuring your content catalog stays current without manual intervention.