Links and Redirects

Splitting a site breaks two kinds of link: the links inside your pages that assume one site, and the links to your pages that live in search engines, bookmarks and other people's websites. The first kind sounds like the bigger job, because there are thousands of pages. The second kind is the one that really matters. This chapter starts by measuring, because the measurement changes the plan.

The Link Audit

The census read every href and src attribute in 4,483 HTML files:

Four facts follow from the census and the cross-site check that came after it:

1. 90% of all links (11,152) are solution .txt links. They are written in many stale forms, and the build already rewrites every one of them from its file name (Learning Website: Framework & Architecture 6). No work.
2. No page links to its own site by absolute URL. There is nothing like https://www.osztromok.com/... to rewrite.
3. Only 55 links leave their own site, and none of them is a real cross-site link. Thirty go to the kanji tiles page, which belongs to the languages area. Twenty-five are example addresses inside lessons, such as /about in a web framework tutorial, not links to your own pages.
4. Relative links are safe: there are only 43 once solution links are set aside, and none crosses a site boundary.

A Rewriter You Hope Not to Need

The content needs no rewriting today, but the first cross-site link someone adds will, so a correct tool belongs in the build. Rules for a safe rewriter:

• Rewrite only what is needed: a root-relative link whose target belongs to a different site becomes an absolute URL on that site; everything else is left exactly as it is.
• Never touch external links, anchors, relative paths or solution links.
• Report what you cannot place (a path in no site) instead of guessing.
• Keep the path, query, fragment and trailing slash exactly.
• Have a dry run that reports changes without writing files.

Exercise 2 builds this on top of the link resolver from Chapter 5. Its dry run over all 4,483 real pages changes nothing, as the audit predicted, and it reports 23 links it cannot place, which are the example addresses inside lessons.

Redirects: Where the Real Work Is

Visitors, bookmarks, search results and other people's pages all use the old addresses. Every one of them must reach the new address in a single hop. The rules should come from the site map, not be written by hand, and their order matters: specific rules must come before general ones.

Exercise 3 generates all 17 rules and tests every old URL. The result: all 4,925 pages, plus two sample resource files, are redirected to the right site; none is matched by no rule; none is sent to the wrong site; and no URL matches rules for two different sites. The only path left unmatched on purpose is /sidebar/ itself, because the sidebar splits across six sites, so decide where the old index page should go (the root landing page is a sensible choice).

Keeping Links Healthy Afterwards

• Check the built site, not the source. After each build, follow every internal link in the output and confirm it reaches a file. The 282 dead tile links found in Chapter 10 are exactly what this finds.
• Check external links on a schedule. The 305 external links (the most common hosts are code.claude.com, github.com, linkedin.com and youtube.com) rot over time. A monthly check is plenty.
• Watch the 404s. The server log shows which old addresses visitors still ask for, which is the best list of redirects you missed.
• Never reuse an old address for different content while its redirect still exists.

Hands-On Exercises