The trailing slash is not cosmetic. It decides which URL your host answers without a redirect, and everything else you write — internal links, canonical, sitemap — has to agree with it.
With build.format: 'directory', Astro emits page/index.html. A static host then serves /page/ directly and sends /page through a 308 to get there. Measured on a site using trailingSlash: 'always' plus the directory format:
curl -o /dev/null -w "%{http_code} %{redirect_url}" https://<site>/about
308 https://<site>/about/
One extra hop per internal link, invisible in the browser, paid by every crawler and every first-time visitor.
The three declarations
-
Config —
trailingSlashandbuild.formatdecide the on-disk shape, which decides what the host serves without a redirect. -
Links in the markup — every
hrefyou typed by hand, in markdown and in components. -
canonicaland the sitemap — declarations of address, not navigational links.
always and never are both defensible; mixing is not. never asks the host to serve /page for a file at /page/index.html, and most static hosts redirect instead of doing that.
There is a fourth place, and it bites on Pages
Cloudflare Pages strips the .html extension. A file you linked as /logo-compare.html is actually served at /logo-compare. If your build emits a clean path and your link keeps the extension, you have a URL that is declared one way and served another — and the redirect makes it look fine in the browser.
Derive two, assert all three
Set the decision once, in config, and generate the other two from it rather than typing them. Then assert, because hand-written URLs drift:
Fetch every URL in your own sitemap and require 200 with no redirect, then compare the canonical tag in that response against the URL you requested. Any mismatch is a place where you declared an address you do not serve.
curl -s https://<site>/sitemap-0.xml | grep -o '<loc>[^<]*' | cut -c6- \
| while read u; do
code=$(curl -s -o /dev/null -w '%{http_code}' "$u")
[ "$code" = 200 ] || echo "REDIRECT/ERR $code $u"
done
Two lines, and it catches the whole class: slash mismatches, .html leftovers, and canonical tags pointing at a URL that redirects.
What this does and does not cost
A 308 is not fatal. Google follows it, and the destination gets indexed. The cost is that you have declared a canonical address that redirects, every internal link is one hop longer than it needs to be, and the sitemap may list URLs that are not the ones being served. None of those is an emergency; all of them are free to fix if you fix the declaration instead of the links.
(The measured version, including the config and the sitemap crawl on our site, is here: https://sitepostmortem.com/build-tools/astro-trailing-slash-mismatch/)
Top comments (0)