Aliases and Redirects

Leed writes a permanent redirect for every URL a page used to live at. You do not switch this on, and you cannot forget it: rename a page, re-slug it, move it into a different documentation folder, and the address it left behind keeps sending visitors to the new one. That is the whole reason renaming is safe.

Everything else on this page is about the redirects you add deliberately.

One vocabulary note before we start. The screens call these redirects, and so does the error message when one is refused. The underlying record is called an alias, which is the word you will see in your published files and in the API. The two mean the same thing; the instructions below use the word on the screen.

Automatic redirects

stateDiagram-v2
    [*] --> Current : the page is published for the first time
    [*] --> Next : you change the slug of a published page
    Next --> [*] : you set the slug back before publishing
    Next --> Current : the page is published
    Current --> Alias : a newer URL is published for this page
    Alias --> Alias : 301, forever

    note right of Next
        A reservation, not a route.
        Nothing else can claim this
        URL while it is held.
    end note

    note right of Alias
        Never expires and is never
        cleaned up. Aliases only
        accumulate.
    end note

The rule in one sentence: when you publish a slug change, the URL you left behind becomes an alias and stays one forever.

Nothing about that is retroactive or partial. A page that has been re-slugged three times owns three aliases, all live, all pointing at whichever URL is current now — never at the intermediate ones, so there is no redirect chain to worry about.

How a URL is composed in the first place, and what a reserved URL is, is on URL Paths and Slugs.

Adding a redirect by hand

Open a page, go to the editor’s Page settings tab, and scroll to Redirects — it sits below the Automations checkboxes (Disable Dynamic CTA, Disable Autolinks) and above Permission Overrides.

Type a path into the Add Redirect… field and it is added straight away, listed on its own line beneath the field. Each entry has a remove control; removing it retires the redirect.

Two things about what you type:

• Type the leading slash. What you enter is used almost verbatim as the source of the generated rule. Leed strips characters that cannot appear in a path and replaces runs of whitespace with hyphens, but it does not add a leading slash or a trailing one for you. Write /old-pricing/, not old pricing.
• A path another page already owns is refused. You get a dialog titled Error Adding Redirect carrying the message “Path already taken”. This is checked against every path in your workspace — current URLs, reserved ones and existing aliases alike — so the answer is to pick a different path, or to retire the redirect that already holds it.

A redirect always belongs to a page. There is no way to create one that points somewhere else, which also means there is no way to accidentally strand one: delete the page and its redirects go with it.

What a hand-added redirect is good for

Migrating a site. Map your old site’s URLs onto the pages that replaced them, one redirect per old address, and inbound links and search rankings carry over instead of landing on a 404. This is the case worth doing thoroughly — every URL you skip is traffic you lose on the day you switch DNS. Do it before the cutover, not after; see How Publishing Works for where in the sequence it belongs.

A short, memorable path. Point /pricing-faq/ at a page four folders deep so it fits on a slide, in an email or on a business card.

Section-wide redirects on a page type

Two controls live on the page type rather than the page, and they are easy to confuse because both produce redirects for a whole section. They do different things.

Aliases

A page-type alias root redirects an entire old section in one rule, preserving whatever follows it. It is the right tool when you renamed a section — or when the site you migrated from used a different word for the same thing — and you do not want to write one redirect per page.

It is not a substitute for per-page redirects when the pages themselves were reorganized, because the wildcard passes the rest of the path through unchanged. /articles/hello/ reaches /blog/hello/ only if a page called hello exists there.

Redirect Index

Redirect Index decides where the section root sends a visitor. It takes four forms:

• first — the first page in the section.
• last — the last page in the section.
• A path starting with / — anywhere on your own site.
• A full URL — anywhere at all.

first and last are resolved at build time against the section’s own page collection, so the destination moves as the section changes. That is usually what you want for a documentation set whose introduction is always the first page.

Both fields are set on the page type in Settings → Page Types; see Configuring a Page Type.

What actually ships

For the curious, and for anyone debugging a redirect that is not firing: all of this becomes lines in a _redirects file generated when your site builds. There is nothing else — no runtime table, no lookup service.

/favicon.ico              /static/images/favicon-2026.png      302
/old-pricing/             /pricing/                            301
/articles/*               /blog/:splat                         301
/docs/                    /docs/what-is-leed/                  302

Reading top to bottom: the favicon rule, one 301 per page alias, one wildcard 301 per page-type alias root, and the Redirect Index pair for each section that sets one. Page aliases reach the build through each page’s own published file, which lists them; the page-type rules come from your page type configuration.

Your local development server reads the same file, so a redirect can be tested before it goes anywhere near production. The file itself is one of the things Leed writes into your repository — see What Leed Writes Into Your Repo.

What redirects will not do

• They are permanent. A 301 tells a search engine the move is final, and browsers cache it aggressively. Reversing a redirect you published is not instant for anyone who has already followed it.
• They do not chain, and do not need to. Leed always writes the redirect straight to the page’s current URL, so a page renamed three times has three redirects to one destination — never a hop through the intermediate addresses.
• They cannot point outside your pages. A hand-added redirect belongs to a page. To send a path to an external destination, use a page type’s Redirect Index, which does accept a full URL, or a tracked short link.
• They do not rescue a page you deleted. Deleting a page removes its paths, including its aliases. If a deleted page’s URL matters, publish something at that address instead, or add the old path as a redirect on whatever replaces it.