Should internal links be relative or absolute? Let's argue about it
Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com There are three ways to link from one page on your site to another: <a href="https://www.example.com/docs/install/">
Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com
There are three ways to link from one page on your site to another:
<a href="https://www.example.com/docs/install/"> <!-- absolute -->
<a href="/docs/install/"> <!-- root-relative -->
<a href="../install/"> <!-- relative -->
All three can point at the same page. They break in completely different situations. And teams argue about this more than you'd think, usually right after a migration in which one of them caused a few thousand broken links.
So which should you use? Let's argue about it.
The case for absolute URLs
They mean the same thing everywhere. An absolute URL doesn't depend on where the page lives, what the <base> tag says, or how the reader got to it. Copy a paragraph into an email, a feed reader, a newsletter or a Slack message, and the link still works.
RSS and syndication need them. Many feed readers don't resolve relative links correctly, and content that gets republished (on dev platforms, aggregators, or by scrapers) loses its base URL entirely. Relative links in a feed are a common source of broken links you never see.
They can't resolve against the wrong base. The classic relative-link bug: href="install/" on /docs/setup resolves to /docs/install/, but on /docs/setup/ (with a trailing slash) it resolves to /docs/setup/install/. A trailing slash change in the router breaks every relative link on the site. Absolute links don't care.
Canonical, Open Graph and sitemap URLs must be absolute anyway. If some URLs on the page must be absolute, making all of them absolute is at least consistent.
The case for relative (or root-relative) links
They survive a domain change. Rebrand, move from .io to .com, add www or remove it, and every absolute internal link either breaks or starts redirecting. Root-relative links (/docs/install/) just keep working.
They work on every environment. Local dev, preview deploys, staging and production all use the same content. With absolute links, every preview deploy links back to production, so you're not actually testing your new pages when you click around a preview. Worse, a staging site with absolute links to production can leak staging into analytics or confuse testers.
They're shorter and easier to move. A docs folder with relative links between its pages can be moved to a different path or a different site without changing any links inside it. Version folders (/v2/, /v3/) depend on this.
HTTP vs HTTPS problems go away. Absolute links written as http:// before a site moved to HTTPS cause redirects at best and mixed-content warnings at worst. Root-relative links inherit the current scheme.
Where I've landed
I don't think "always absolute" or "always relative" is right. I'd split it by where the link lives:
-
Templates and navigation: root-relative (
/pricing/). Works on every environment, survives domain changes, and never depends on the current page's depth. -
Content in a docs tree that moves as a unit: relative, but generated, not hand-written. Write links to source files (
[Install](../install.md)) and let the build convert them. Most docs tools can validate these at build time, which catches broken ones before they ship. - Anything that leaves your site: absolute. RSS and Atom feeds, emails, Open Graph tags, canonicals, sitemaps, JSON-LD, API responses that include links. Generate them from a single configured base URL at build time, never by hand.
-
Never
http://and never a hard-coded staging or preview host in either form. Search your content for them before every migration. - Check the built output, not the source. Whatever style you choose, the links that matter are the ones in the HTML a browser receives.
Every one of these choices has a failure mode, and they all show up as broken links after a move. linkbruno.com checks the live site on a schedule, so a trailing-slash change that breaks relative links, or an old absolute link left behind after a domain move, shows up in a report the same day.
What makes this hard
- CMS editors paste absolute URLs. Copy the address bar, paste into a link field. Some CMSes rewrite these to relative on save, some don't. Content written over years ends up with a mix of everything.
-
Protocol-relative links (
//example.com/) used to be recommended for HTTP/HTTPS sites. Today they're mostly a historical oddity and occasionally break in contexts like email clients andfile://previews. -
Multi-domain setups. If your docs live on
docs.example.comand your app onapp.example.com, links between them must be absolute, so the "always relative" rule can't apply everywhere anyway. -
Base tags. A
<base href>makes relative links resolve against a fixed URL. It fixes some problems and causes subtle new ones, especially with in-page#anchorlinks, which then resolve against the base instead of the current page.
A quick check for your own site
Count what you have today:
curl -s https://www.example.com/docs/ | grep -oE 'href="[^"]+"' | cut -d'"' -f2 \
| awk '/^(https?:)?\/\//{print "absolute"; next}
/^\//{print "root-relative"; next}
/^(#|mailto:|tel:)/{print "other"; next}
{print "relative"}' | sort | uniq -c
It's rough, but it usually shows a mix. The mix itself isn't a problem. The problem is the next migration where nobody knows which kind of link is where.
And Markdown on GitHub?
READMEs and docs that are read on GitHub and built into a docs site add another wrinkle. A relative link like [Install](docs/install.md) works perfectly in GitHub's file view and in most docs builds. An absolute link to https://github.com/you/repo/blob/main/docs/install.md works on GitHub and on npm, but breaks the moment someone renames the branch or the file. For repositories, I'd keep relative links in the source and rely on the docs build to rewrite them.
Related reading
- The anatomy of a URL, and which part of it broke your link
- Markdown links in a monorepo: 7 things I'd do differently after the third big folder move
- How to find mixed content (http:// links) on an HTTPS site
- Should your docs link to GitHub's main branch or to a permalink? Both options rot.
- How to check every link in your HTML email templates before they're sent (a Python script for CI)
Which way does your team go? And which kind of link broke the most during your last migration?
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.