---
title: Forward visitors from a renamed page
description: "Set redirectUrl in front matter to forward visitors from the old path to the new one — an HTTP 301 on the live server, plus a meta-refresh stub in the static build."
canonical_url: https://usepennington.net/how-to/pages/redirects/
sidecar_url: https://usepennington.net/how-to/pages/redirects.md
content_hash: sha256:24e8eb38666f5110bd59c8a94363acca7c4c2636fea23a93a2df5e20bd3dc9fb
tokens: 1064
uid: how-to.pages.redirects
reading_time_minutes: 3
---

Guides
# Forward visitors from a renamed page

Set redirectUrl in front matter to forward visitors from the old path to the new one — an HTTP 301 on the live server, plus a meta-refresh stub in the static build.

 
When a published page is renamed or deleted, set `redirectUrl:` in its front matter to forward visitors to the new URL. On the dev and self-hosted server, Pennington issues a real HTTP 301 from the old path; the page body is not rendered or indexed. The static build also writes a `<meta http-equiv="refresh">` stub at the old path, since a static host can't issue a server-side 301 without its own redirect config.

 
When the page is *deleted* rather than renamed, keep the file as a front-matter-only stub at the old path — `title:` and `redirectUrl:` with no body — so the old URL still resolves to a redirect. Delete the file and the old URL 404s.

 
`redirectUrl:` accepts an external absolute URL (`https://…`) as well as an internal path; the value is emitted verbatim as the 301 `Location` and the meta-refresh target, so a cross-site redirect works the same way.

 
For batch redirects across many paths, configure them at the hosting layer instead — Nginx or IIS rules (see [Self-host behind Nginx or IIS](https://usepennington.net/how-to/deployment/self-host.md)) or a Netlify/Cloudflare/Azure rules file (see [Adapt the deploy workflow for other hosts](https://usepennington.net/how-to/deployment/adapt-for-other-hosts.md)).

 
## Before you begin

 
 - An existing Pennington site using `AddDocSite` (see [Scaffold a documentation site with DocSite](https://usepennington.net/tutorials/docsite/scaffold.md) if not) or another host whose front-matter type implements `IRedirectable`. `DocSiteFrontMatter` and `BlogSiteFrontMatter` both do. For a custom record, add the interface — see [The front-matter capability system](https://usepennington.net/explanation/core/front-matter-capabilities.md).
 - Both the old URL (the page being retired) and the new URL (the canonical destination) are known.
 
 
To copy a working setup, see [examples/DocSiteKitchenSinkExample](https://github.com/usepennington/pennington/tree/main/examples/DocSiteKitchenSinkExample), whose `Content/main/redirect-source.md` is a complete redirect page.

 
## Add `redirectUrl:` to the old page

 
Open the markdown file at the old URL and set `redirectUrl:` to the new absolute path. Keep `title:` so diagnostics stay readable; the body does not render.

 
```markdown:symbol
---
title: Old page URL
description: Redirects away to the new location.
redirectUrl: /main/front-matter/
order: 200
uid: kitchen-sink.main.redirect-source
---
  
A visit to this URL is intercepted by the Pennington redirect middleware
and returns HTTP 301 with a meta-refresh body pointing at `redirectUrl`.
The static build captures the same 301 and writes the meta-refresh file
to disk at this page's output path — one code path for dev and publish.
```

 
## Verify

 
 - Run `dotnet run` and visit the old URL: the page redirects immediately to the target set in `redirectUrl`.
 - View source on the old URL: the markup contains `<meta http-equiv="refresh" content="0;url=...">` and a `<link rel="canonical" href="...">` pointing at the redirect target.
 - Check `/sitemap.xml` and `/llms.txt`: the old URL does not appear. A redirect has no canonical HTML page, so it is excluded from both.
 
 
## Related

 
 - Reference: [Front matter key reference](https://usepennington.net/reference/front-matter/keys.md) — the row for `redirectUrl` (type, default, which records support it).
 - Reference: [IFrontMatter and capability defaults](https://usepennington.net/reference/api/i-front-matter.md) — how `IRedirectable` fits alongside the other capability interfaces.
 - Background: [The front-matter capability system](https://usepennington.net/explanation/core/front-matter-capabilities.md) — why `IRedirectable` stayed a separate capability instead of collapsing into `IFrontMatter`.
 
 
[Previous
                
                Add images and shared assets to a page](https://usepennington.net/how-to/pages/images-and-assets.md)[Next
                    
                Reuse one snippet across many pages](https://usepennington.net/how-to/pages/include-shared-content.md)