Subdomain to Subfolder Migration: Planning the Move
Direct Answer
Map sub.example.com/path to www.example.com/sub/path (or the chosen folder) one URL at a time. Update absolute links and host-specific configuration, and verify that the destination folder inherits the correct canonical, hreflang, robots, cache, cookie, and application routing behavior. For ordinary users this means old bookmarks and links should resolve reliably to the correct new state. For developers it means every participating layer needs a measurable expected-versus-observed test. Moving docs.example.com/topic to example.com/docs/topic changes both the hostname and path. Build an explicit mapping, keep the source subdomain online, redirect each old URL directly to its new subfolder equivalent, and update internal links, canonicals, hreflang, sitemaps, APIs, and asset references. Do not rely on a wildcard rule until you have proven that path patterns are truly one-to-one.
Documentation
What this check actually means
Map sub.example.com/path to www.example.com/sub/path (or the chosen folder) one URL at a time. Update absolute links and host-specific configuration, and verify that the destination folder inherits the correct canonical, hreflang, robots, cache, cookie, and application routing behavior.
Expected behavior and decision boundary
Expected state: Map sub.example.com/path to www.example.com/sub/path (or the chosen folder) one URL at a time. Update absolute links and host-specific configuration, and verify that the destination folder inherits the correct canonical, hreflang, robots, cache, cookie, and application routing behavior. Define an expected status, expected destination, and owner for every URL/host class before launch. PASS means observed HTTP/DNS/DOM behavior matches that definition without unexplained intermediate states.
Diagnosis: evidence to capture
Record the test as data so release and SEO teams see the same state:
url,expected_status,actual_status,expected_target,actual_target,canonical,robots,owner
https://old.example/a,301,301,https://new.example/a,https://new.example/a,https://new.example/a,index,platform
For host or infrastructure changes, also store DNS answers, TLS/SNI result, CDN cache status, and timestamps. A screenshot alone cannot prove an HTTP status, redirect chain, or resolver state.
Technical implementation
Map sub.example.com/path to www.example.com/sub/path (or the chosen folder) one URL at a time. Update absolute links and host-specific configuration, and verify that the destination folder inherits the correct canonical, hreflang, robots, cache, cookie, and application routing behavior.
curl -I https://old.example/path
curl -IL https://old.example/path
curl -I https://new.example/path
Common root causes
Common causes are incomplete URL inventories, changing domain/CMS/design at the same time, untested edge rules, old absolute URLs embedded in templates, staging/production configuration drift, and no explicit rollback boundary. When something fails, first locate the layer: DNS/TLS, web server/CDN, application routing, CMS/template, or page-level metadata.
Edge cases and false positives
Not every difference is a defect: an intentional 404/410 can be correct, a temporary 302 may be right for testing, and DNS answers can differ while TTLs expire. Define expected behavior per URL class before auto-fixing deviations. For login/API/non-GET endpoints, review redirect semantics separately.
Verification after the fix
| Check | PASS | FAIL | | --- | --- | --- | | Output | expected rule is visible in final HTML/HTTP/DOM | backend field looks correct but final output does not | | Scope | representative URLs from every affected template tested | only one example URL tested | | Source | shared root cause/owner is documented | manual per-page edits without root cause | | Regression | adjacent canonical/robots/accessibility/link rules still pass | fix creates a new defect in the same component | | Evidence | before/after values and test time are stored | only visual impression or screenshot |
Ownership and handoff
Content/SEO owner: defines the expected page purpose and whether the condition actually requires a change.
Developer/platform: fixes the shared template, routing, header, or component source.
QA: tests representative edge states and re-crawls/re-requests after deployment.
Release owner: records time, scope, and rollback point so monitoring signals can be tied to a specific change.
Acceptance criteria
PASS when the final technical state is reproducible on representative URLs, the shared root cause is fixed, intentional exceptions are documented, and a re-crawl/re-request shows no new regression in canonicalization, robots directives, accessibility, links, or rendering.
Worked operational example: defect → fix → proof
Symptom: the audit reports “Subdomain to Subfolder Migration: Planning the Move” on multiple URLs.
Root cause: the repeated output originates in a template, component, CMS fallback, or infrastructure layer.
Fix: change that shared source instead of patching individual pages, and keep the change as small as possible.
Proof: store at least one before/after URL per template, the final HTTP/HTML/DOM output, and the re-crawl result. If an intentional exception remains different, document it so a future audit does not treat it as an unresolved defect.
For production systems, also include a regression sample: same locale, mobile/desktop when relevant, missing-data state, and one URL that was already correct. This proves whether the change stabilizes the generator rather than only the reported example.
Questions & Answers
Should a migration and redesign happen at the same time?
Prefer separating them when practical. Fewer simultaneous changes make root-cause analysis, rollback, and search fluctuations much easier to interpret.
How should redirects be tested?
First request without following redirects and verify the initial status and Location; then inspect the full chain and final 200 destination. A successful end page does not prove the path is clean.
What should be monitored first after launch?
HTTP errors, robots/noindex, redirect targets, canonicals, sitemap output, and server/CDN failures first; indexing and query trends require a longer window.
When is rollback better than a hotfix?
When the defect is broad, the cause is uncertain, or routing/indexability is severely damaged and a known-compatible rollback is available.
Practical Check
- Define the affected URL/template class and write the expected behavior before changing anything.
- Capture raw HTTP/HTML; when client-side code changes output, also inspect the rendered DOM.
- Validate the redirect/status matrix against final destinations; do not start with a follow-redirect-only test.
- Trace the defect to its shared layer: DNS/CDN, routing, template, component, CMS field, or editorial content.
- Implement the smallest systemic fix and preserve a rollback point first.
- Test positive cases, missing/empty data, and at least one relevant edge state.
- Re-crawl or re-request every affected template/URL class and store before/after evidence.
- PASS: expected behavior is reproducible, no adjacent SEO/accessibility rule regresses, and the fix does not require manual per-page workarounds.