The full URL Mappings grammar fits in one line: source -> destination status. The arrow is -> (no space inside). The status code is 301 or 302, nothing else1. Wildcards use square-bracket placeholders. External targets must start with https://. Squarespace matches top-down, so order matters when wildcards are present.
This page is the reference. Six sections, every rule shape Squarespace accepts and rejects, with the typed-out grammar and the failure cases the forum threads document. Use it as a checklist before pasting any redirect map.
§01Grammar
The grammar in one line
Every Squarespace URL Mapping has three parts separated by single spaces: a source path, the literal arrow `->`, a destination, then a status code. The source is a relative path starting with /. The destination is either a relative path starting with / or a full URL starting with https://. The status code is 301 or 302. Whitespace is significant — one space on each side of the arrow, one space before the status code. Extra whitespace, missing whitespace, or any other arrow shape rejects on save.
URL MappingsThe grammar — every rule has this shape
One rule per line. Blank lines are ignored by the parser and act as visual separators only. Comment syntax is not supported — there is no # or // comment marker. If you need notes alongside rules, store them in your source spreadsheet, not in the panel.
§02Status
Status codes accepted
Two status codes are accepted: 301 (permanent) and 302 (temporary). Every other code — 303, 307, 308, even 200 — rejects on save with a syntax error. Use 301 for permanent URL moves. Google passes full PageRank through 301s and treats them as the canonical permanent-move signal. Use 302 only when the move is genuinely reversible — a temporary maintenance page, a soft-launch redirect that you plan to roll back.
The status-code matrix
301
permanent redirect. Use this for every URL change you do not plan to roll back. Google consolidates ranking signals.
Squarespace supports placeholder syntax with square brackets. A rule like /blog/[slug] -> /journal/[slug] 301 matches any URL under /blog/ and passes the path segment through to /journal/. The bracketed name is just a label — Squarespace uses it to capture the matched segment, not to validate the value. Multiple placeholders in one rule are supported: /shop/[category]/[product] -> /[category]/[product] 301 captures both segments and passes them through unchanged.
URL MappingsWildcard patterns Squarespace accepts
# Single placeholder/blog/[slug]->/journal/[slug]301# Two placeholders in source AND destination/shop/[cat]/[product]->/[cat]/[product]301# Placeholder discarded in destination (collapse path)/old-folder/[anything]->/services301# Date-based blog URLs flattened to slug/blog/[year]/[month]/[slug]->/blog/[slug]301
Wildcards do not match across path separators. /blog/[slug] matches /blog/post-name but does not match /blog/old-cat/post-name — the second path has an extra segment that the single placeholder does not cover. Use /blog/[cat]/[slug] to match the two-segment case.
§04External
External targets
A destination can be a full URL on a different domain. The constraint: the destination must begin with https:// (http:// is rejected on save), and the URL must resolve to a real hostname. Squarespace does not validate that the destination URL itself returns a 200, but it does check that the URL is well-formed and uses HTTPS. Use external redirects for booking platforms, payment processors, or any case where you want a vanity URL on your Squarespace domain to redirect to a third-party host.
# Vanity URL pointing at a booking platform/book->https://calendly.com/your-handle301# Affiliate or partner outbound link/partner->https://example.com/partner-program?ref=yoursite302# Wildcards work for external too/courses/[slug]->https://teachable.example.com/courses/[slug]301
§05Order
Order of precedence — top-down match
Squarespace evaluates the URL Mappings panel top-down: the first rule whose source pattern matches the incoming URL wins. This means rule order changes behaviour. A wildcard placed near the top of the panel absorbs URLs that more specific rules lower in the panel were meant to catch. The fix is reordering: specific rules at the top, wildcards at the bottom.
URL MappingsCorrect ordering — specific first, wildcard last
# 1. Specific rules at the top/blog/feature-launch->/announcements/launch301/blog/2024-recap->/announcements/year-in-review301# 2. Wildcard at the bottom catches everything else/blog/[slug]->/journal/[slug]301
§06Rejection
What the panel rejects on save
Squarespace's URL Mappings validator rejects rules on save with a line-number error when any of these conditions fail. The panel highlights the offending line and the rest of the panel does not save until the error is resolved. Most rejections come from one of seven patterns. Knowing the list shortens debugging from minutes to seconds.
The seven rejection patterns:
Wrong arrow.=>, -->, ->>, or -> with an internal space all fail. Only the exact two-character sequence -> succeeds.
Wrong status code. Anything other than 301 or 302 rejects — including 200, 307, 308, and any text label like permanent.
Missing status code. A rule like /old -> /new with no status code fails — the code is required.
Source not starting with /. The source must be a relative path beginning with a slash. old-page -> /new-page 301 fails.
External target not using https://./old -> http://example.com 301 or /old -> example.com 301 both fail.
Redirect from /. Squarespace does not allow redirecting the homepage root. / -> /new-home 301 rejects.
Multiple statements on one line. Each rule must occupy its own line; semicolons or comma-separated rules on one line fail.
The validator error names the failing line by number. The fastest debugging workflow is to count down to that line in your source spreadsheet, find the row, and look for one of the seven patterns above. Almost every rejection is one of these seven.
