A client wanted to migrate content sources gradually, some content in a headless CMS, some still in markdown files scattered across the existing repository, without a disruptive big-bang cutover that would force every content type to move at once. Astro's Content Layer API let us build a unified content model that doesn't care where any given piece of content actually lives, which turned a migration that would otherwise have needed careful coordination across the whole site into something that could happen piece by piece on its own schedule.
Pages query the same content interface regardless of source, which means the migration can happen content type by content type, with zero changes needed on the frontend each time another type moves over from markdown into the headless CMS. A page template that renders a blog post doesn't know or care whether that particular post's data came from a markdown file parsed at build time or an API call to the CMS, both arrive through the same content interface with the same shape, so the rendering logic never needs to change no matter how much progress the underlying migration has made.
That decoupling turned out to matter for more than just this one migration. A few months after the initial project wrapped, the client asked about eventually moving away from their current CMS entirely in favor of a different vendor, a conversation that would have been far more daunting if the frontend had direct, hardcoded knowledge of the current CMS's specific API shape scattered across every template. Because the Content Layer abstraction already sits between the templates and the actual content source, that future migration, whenever the client decides to pursue it, has a much smaller blast radius than it would have without this architecture in place.
The content types that stayed in markdown throughout the project weren't leftovers waiting their turn, some genuinely made more sense staying there long-term, internal documentation-style pages maintained directly by developers, for instance, where a markdown file in the repository is a better fit than routing through a CMS built for a marketing team's editorial workflow. The Content Layer API let us make that a deliberate per-content-type decision rather than an all-or-nothing choice forced by the migration itself.
Build-time performance stayed solid even as we mixed content sources with genuinely different fetch characteristics, static markdown parsed instantly at build time alongside API calls to the CMS that carried real network latency. Astro's caching and incremental build behavior handled that mix well enough that we didn't need to build any custom caching logic ourselves to keep build times reasonable as the number of API-backed content types grew over the course of the migration.
For any team facing a similar gradual content migration, decoupling the frontend from any single content source early is worth the modest upfront investment, even if a full migration to a new source isn't imminent yet. The option value of being able to move a content type without touching every template that renders it has already paid off once for this client, and we expect it to keep paying off as their content strategy continues to evolve.