Rendered HTML Migration Comparison Worksheet

Purpose

Use this worksheet to record the differences between old and new rendered HTML for priority templates. It is designed to make expected changes explicit, surface unexpected SEO‑critical differences and decide whether each difference blocks launch.

Use it to make accidental changes visible before launch: missing headings, weaker internal links, generic metadata, broken canonicals, lost structured data, thin server output, or client‑side behaviour that hides search‑critical content.

Who This Is For

• Developers migrating React, Next.js, Gatsby, WordPress, Drupal, Shopify or headless CMS templates.
• Technical SEOs checking whether a replatform preserves crawlable and indexable page evidence.
• Product, content or marketing teams that need a clear launch gate before search‑critical URLs move.
• Technical leads reviewing agency or delivery‑team output before final cutover.

When to Use This

• Before a Next.js migration or other front‑end replatform where templates, routing or rendering strategy are changing.
• Before a CMS migration where field names, rich text rendering, previews, slugs or metadata sources may change.
• Before a redesign where the visual layout is changing but important landing pages need to keep their meaning.
• After launch, if traffic, indexation or rich‑result eligibility has changed and you need to isolate what the new HTML now says.

How to Use This Worksheet

• Choose representative URL groups first: home page, service pages, article pages, case studies, high‑value landing pages, category pages, product pages and any template with structured data.
• Capture old and new output using the same method for each row. Do not compare view‑source from one site with post‑hydration DOM from another unless the difference is intentional.
• Record whether each difference is expected, acceptable, risky or blocking. A planned improvement is not a failure, but it still needs evidence.
• Assign an owner for each failed comparison. Rendered HTML issues often sit between front‑end code, CMS fields, SEO requirements and deployment configuration.

Worksheet Columns

• Page group: the template or business area being sampled, such as service page, article, case study, product detail page or location page.
• Old URL and new URL: the live source URL and the target URL after migration, including redirect destination if the address changes.
• Capture method: server response, view‑source, rendered DOM after hydration, crawl output, rich‑result validation or another agreed evidence source.
• Must‑match signals: status code, canonical, title, meta description, robots directives, H1, primary copy, internal links, schema and sitemap inclusion.
• Expected differences: deliberate copy, design, URL, metadata or schema changes that should not be treated as regressions.
• Risk level: red for launch blockers, amber for monitored or owned follow‑up, green for acceptable parity or deliberate improvement.
• Owner and launch gate: who fixes or accepts the difference, and what evidence is required before the URL group can launch.

What to Compare First

• HTTP status and final URL after redirects, including slash behaviour, casing, query handling and redirect chains.
• Canonical URL, title, meta description and robots directives in the final rendered document.
• H1, heading outline and the main visible content that explains the page topic.
• Navigation, breadcrumbs, pagination and internal links that search engines can discover without fragile client‑side state.
• JSON‑LD structured data, including page type, author or provider identity, breadcrumbs, article data, service context and visible evidence. Schema should match the page. It does not guarantee rankings, rich results or AI visibility.
• CMS‑rendered rich text, images, alt text, media captions, tables, lists and reusable content blocks.
• Hydration changes that remove, rewrite or delay important content after the initial response.
• Sitemap inclusion, noindex handling and robots rules for the same URL group.

React and Next.js Checks

• Compare server output and post‑hydration DOM separately where the route depends on client components, deferred data, draft mode, middleware or incremental regeneration.
• Check that metadata helpers do not fall back to generic titles, descriptions or canonical URLs when CMS fields are missing.
• Confirm that route groups, dynamic params and redirect helpers produce the expected public URLs, not framework‑shaped internal assumptions.
• Do not assume that using Next.js makes the page SEO‑safe. The framework gives teams useful rendering options, but the shipped document still has to be inspected.

Headless CMS Checks

• Map old fields to new fields before comparing page output. A renamed CMS field can become a missing title, empty schema value or wrong canonical without obvious visual breakage.
• Check rich text renderers against paragraphs, headings, lists, links, embedded entries, tables and code blocks.
• Verify preview and published output separately when draft content, fallback values or release scheduling can change what appears on the page.
• Confirm that structured data, breadcrumbs, sitemap inclusion and social metadata are generated from stable content fields rather than layout‑only assumptions.

Launch Gate Examples

• No priority URL launches with an unexpected noindex directive, blocked robots path, broken canonical or missing primary heading.
• Every changed URL has an expected redirect destination and no avoidable redirect chain.
• Priority page types retain crawlable internal links and meaningful rendered body copy.
• Structured data is valid, supported, proportional and consistent with visible content.
• Known differences are documented as deliberate changes, with owner approval and a post‑launch monitoring point.

Worked Example: Five Fixes Before Launch

Here's what a completed review looks like. I've put together a small, deliberately faulty migration so you can follow each decision back to the HTML. It covers a service page, a preview guide, and a case study. The pages, people, release brief, and approvals are all fictional; they don't describe a client project.

The worked migration evidence pack contains the old, candidate, and corrected HTML, the URL map, the agreed changes, a completed report, and a small verification script. It uses reserved .example addresses. You can inspect the files directly or reproduce the checks with Python 3.10 or later, using only its standard library.

The Release Being Reviewed

This example moves three legacy .html pages to new public URLs. The case study also moves from a projects directory to a case‑studies directory. The candidate files represent the HTML intended for public release, rather than a protected staging site where keeping noindex could be deliberate.

These are authored HTML fixtures, not captured HTTP responses or browser sessions. All three versions use the same file‑level comparison. The separate launch checks remain open below.

Before checking for regressions, the fictional release brief accepts four groups of changes:

• A different header, navigation treatment, footer, and layout. Visual and accessibility acceptance still need their own checks.
• Specific new page titles and H1 wording. For example, "Content Migration Services" becomes "Headless Content Migration Support". This is not permission to accept any title change.
• Rewritten introductions. The substantive guidance beneath them must remain unless a separate change is agreed.
• The recorded URL moves, including updated internal references and author identifiers. A URL map records intent; it does not prove that redirects work.

Which Differences Need Action?

The first comparison finds four reasons to hold the affected pages and one authorship question for review. The decisions below follow this release brief. They are not a universal severity scale for every migration.

The distinction matters with canonicals. A move from the old URL to its agreed replacement is expected; a move to the preview host is not. Google treats canonical annotations as signals, so checking the tag confirms the implementation, not which URL Google will ultimately select.

Google must be able to crawl a page to see its noindex directive. The guide's saved tag establishes an unwanted release setting here. Whether a crawler has fetched the page, and what is currently indexed, require separate evidence.

What the Retest Establishes

The corrected files restore the public canonical, remove the unintended noindex, restore the linked‑draft instructions, repair the enquiry destination, and align the author reference with the visible attribution. Repeating the same checks leaves none of those five findings open.

All three corrected pages still differ from their old versions. They keep the approved titles, introductions, URL moves, and redesign. Reverting the whole page until a text diff goes quiet would undo the changes we actually wanted.

My decision at this point would be: accept these five corrections within the HTML review; keep overall launch approval open. We have not checked HTTP statuses, redirect chains, response headers, robots.txt, sitemaps, JavaScript rendering, accessibility, or the remaining pages. The script does not award an SEO score, validate all structured data, or predict rankings.

Where Your Existing Crawler Fits

Screaming Frog's crawl comparison already reports changes to content, headings, links, metadata, and structured data, and supports URL mapping. Use that output with this worksheet when reviewing a real migration. The example adds the part a list of differences leaves you to work through: what was agreed, what changed unexpectedly, who decides, and which evidence closes the finding.

The included script only checks this small example against its stated requirements. It is not a general website auditor. If your existing crawler and a short decision record do the job, you don't need another comparison tool.

Common Failure Patterns

• A redesign keeps the page looking correct but removes useful headings, intro copy or internal links from the rendered document.
• A CMS migration imports content successfully but changes the source fields used for metadata, schema or canonical generation.
• A React component turns crawlable links into buttons or client‑side state changes.
• A dynamic route returns a 200 page with a thin error state instead of the correct status code.
• JSON‑LD helpers survive the migration but lose required values because the new content model uses different names.
• Staging domains, preview URLs or old hostnames leak into canonicals, Open Graph tags, sitemaps or structured data.

Expected Output

The useful output is a short comparison matrix, not a long detached audit. By the end, each priority URL group should have a clear parity status, a list of accepted changes, any launch blockers, and the owner responsible for each unresolved difference.