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.

The same record can be made without opening the page. Over MCP it is the create_path_alias and delete_path_alias tools, the second of which asks for confirmation before it runs. From the CLI it is leed settings path create <pageId> <path> and leed settings path delete <id>, where the id is the numeric one leed settings path list prints.

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.

A documentation or API set’s starting page takes priority over Redirect Index. When the page type’s own documentation configuration names a startingPage that resolves to a page, the section root sends visitors there with a single 302 and Redirect Index is not used. A starting page inherited from the company default does not count. And when a page actually renders at the section root, neither rule is written, so a real index page is never shadowed by a redirect.

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
/docs/                    /docs/what-is-leed/                  302
/articles/*               /blog/:splat                         301

Reading top to bottom: the favicon rule, one 301 per page alias, each section’s root rule — its starting page, or its Redirect Index pair — and last, one wildcard 301 per page-type alias. The wildcards go last because Cloudflare counts every rule after the first wildcard against a much smaller limit. 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.

Each source path appears in the file once, because Cloudflare rejects the whole file over a duplicate. When two rules claim the same path, one is kept — the favicon first, then a section root, then a page alias, then a wildcard — and the build logs an error naming the rule it dropped. A rule that could never work is dropped the same way before that: one whose source is an absolute URL, one that redirects a path to itself, or a page alias written as a pattern.

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 cannot be patterns. A hand-added redirect is one literal path. One containing * or a :name placeholder, such as /documentation/*, is dropped from the build with an error rather than allowed to capture a whole section. To redirect a whole section, use a page type’s Aliases.
• 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.