Migrating One Area
Learning Website: Framework & Architecture
Chapter 10 · Migrating One Area at a Time
You now have a design for the family of sites: a site map, a content model, a shared design layer, three layers of navigation, a pipeline, search and sitemaps, and hosting. What remains is the hardest part, which is getting from the site you have to the sites you want without breaking what works. The safe way is not to rebuild everything and switch over on one weekend. It is to move one area at a time while the old site keeps running. This chapter works through that plan for the languages area, using measurements of your real site.
The Strangler Pattern
The approach is usually called the strangler pattern, after a vine that grows around a tree until it can stand on its own. The new sites grow around the old one. For a while both exist. Each area that moves is verified, redirected and then retired from the old site, so the old site shrinks as the new ones grow, until there is nothing left to retire. At every moment there is a working site, and until an area is retired there is a way back.
Why Languages First
You chose languages first because it is the fastest-growing area. The measurements say it is also the easiest area to move. Exercise 1 scanned the 593 language pages for links:
| Link type | Count | What it means for the move |
|---|---|---|
| From languages to another area | 0 | Nothing in these pages needs a cross-site link |
| Into languages from another area | 0 | No other page needs updating |
| Within languages | 225 | Stay relative; they keep working |
To resource files (/resources/japanese/...) | 23 | The files must move with the area |
| To the kanji tiles page (a special route) | 30 | That page moves with the area |
| To a page that does not exist | 282 | An existing bug: fix it first |
A clean cut with no links in or out is rare. It means the cross-site navigation work from Chapter 5 is not even needed for the first move, and every later area can be measured the same way before its turn.
/japan/hiragana/hiragana-tiles or /japan/katakana/katakana-tiles. The folders
contain the tile content (hiragana_tiles_cms_content.html and its katakana twin), but only the
kanji tiles file has a page that routes it. Those links are dead on the current site (checked against the built
output). Fix them on the old site first, so the new site starts clean and you can tell whether a later
failure is new.Update: this was fixed after the course was written, by adding the two missing pages (
hiragana-tiles.astro and katakana-tiles.astro, modelled on the kanji
one). A rebuild and the link check of Chapter 12 then showed the 282 broken links gone.
The Phases
| Phase | What happens | The way back |
|---|---|---|
| 0. Prepare | Measure, fix known bugs, scan for secrets, decide the exceptions | Nothing has changed yet |
| 1. Build in parallel | New subdomain, certificate and virtual host; first release deployed; crawling blocked | Delete the new site; the old one is untouched |
| 2. Verify | Compare pages, links, files and visuals against the old site | The old site still serves everyone |
| 3. Rehearse redirects | Turn on the redirect rule as 302 (temporary) and test every old URL | Remove the rule |
| 4. Switch | Allow crawling, submit the sitemap, change redirects to 301, replace the old menu entry with a link | Switch the rule back to 302 or remove it |
| 5. Watch | Logs, Search Console, visitor reports, for several weeks | As above |
| 6. Retire | Remove the area from the old site's build; keep redirects for at least a year | Restore from the content folder and the release history |
The block on crawling in phase 1 matters because, until the switch, both sites would serve the same pages. Search engines should find the pages in one place only (Chapter 7's rule about one address per page).
Verify with Scripts, Not Eyes
During phase 2 the question is “did every page survive?”. Compare two sets: the pages the content tree says should exist, and the pages that were actually built, in both directions. Exercise 2 does this on today's build as a rehearsal:
_print), some resource folders, the home page, the admin dashboard and the course index.
So the print versions are real, public pages. Decide what you want for them (keep, point a canonical link at the
main page, or ask search engines not to index them), and then the migration will not surprise you with them.
Use the same check on the new site, with the area's expected pages against its output folder. The goal is zero missing pages and an extras list you can explain line by line.
The Exceptions List
Pages move by their folder, but some things are not content folders. Exercise 3 inventories them from the real
public/ folder:
| Item | Size | Decision |
|---|---|---|
/resources/japanese/ | 312 files, 1.6 MB | Moves with the languages area |
/resources/hungarian/ | 11 files, 104.8 MB | Moves with the area, after checking (see below) |
/japan/kanji-tiles/ | one page | Moves with the area |
| Other resource folders | csset, jquery, js, js2021, linux, php, postman | Not language assets: they stay until their own areas move |
/resources/hungarian/ holds PDFs, a video and screenshots, and their names look like a published
Hungarian textbook and a lesson recording. Before copying them to a new public site, check that you have the
right to publish them (the course Copyright & Fair Use covers this), and consider whether 100 MB of video
belongs in the web root at all. A move is a good moment to clean up.
Running Side by Side
For the duration of the migration the old site's virtual host does not change; the new one is added beside it (Chapter 8). The old site's menu and the new site's global bar link to each other so that visitors can find their way. The only place the two meet is the redirect rule on the old site, which stays off until phase 3. During the move, treat the content folder as the single source for both: the old site builds from it, the new site builds from it, and a correction in one place appears in both until the area is retired.
After the Switch
- Redirects stay for at least a year, and ideally forever, because old links live in other people's bookmarks and pages.
- The old menu entry changes from a dropdown of language courses to a single link to the new site.
- Search Console: add the new site, submit its sitemap, and watch crawl errors and coverage for the old addresses.
- Then repeat for the next area: measure its links, list its exceptions, fix its bugs, and follow the same phases.
Hands-On Exercises
Write a link inventory for one area: count its links to its own pages, to other areas, to special routes and to resource files, count links into it from other areas, and check that every target exists. Run it on the languages area and say what it tells you about the move.
📄 View solutionWrite a parity check that compares the pages the content tree expects with the pages in a build output, reporting pages missing from the build and pages built but not expected. Run it on the current site's build and explain the extras.
📄 View solutionInventory the resource folders and special routes that do not move by the folder rule, decide where each goes, and write a seven-phase cutover plan for the languages area with a way back at every phase.
📄 View solutionChapter 10 Quick Reference
- Strangler pattern: new sites grow around the old; move, verify, redirect, retire one area at a time
- Languages is the first area: 0 links in or out across 593 pages, so it is a clean cut
- Fix existing bugs first: 282 dead back-links (hiragana and katakana tile pages)
- Phases: prepare, build in parallel (crawling blocked), verify, rehearse with 302, switch with 301, watch, retire
- Verify with scripts: expected pages against built pages, in both directions
- The current build has 0 missing pages and 89 unplanned ones (mainly print variants)
- List what does not move by folder: resource folders and special routes
- Check
/resources/hungarian/(104.8 MB) before copying it to a new site - Keep redirects at least a year; change the old menu entry into a link; repeat for the next area