Moving a post doesn't make its old links disappear: external references, search-engine indexes, and readers' bookmarks all still point at the old address. xfm-plugin-redirect writes a tiny redirect page at every old address so those entry points keep working instead of hitting a 404.
What it solves
Migrating posts, restructuring URLs, or moving from another blog system all leave a trail of dead addresses. This plugin maps old URLs to new ones at build time and emits real HTML files, so plain static hosting works with no server-side config.
Each redirect page has three layers of fallback, so it works everywhere:
meta refresh— browsers with JavaScript disabled still redirectlocation.replace— an instant redirect in JS environments that doesn't pollute browser history- A visible link — if everything else fails, the reader can click through manually
Installation and configuration
npm i -D xfm-plugin-redirectTwo ways to declare redirects, pick by scenario:
// xfm.config.mjs
export default {
plugins: ['redirect'],
redirects: {
'/old-post/': '/posts/new-post/',
'/2020/01/hello.html': 'https://example.com/hello/',
},
};- Global map: declare
old → newpairs in theredirectsconfig, best for site-wide rules. Targets can be site paths or absolutehttps://URLs - With the page: write
redirect_from(or its aliasaliases) in the post's own front-matter — handiest when changing an address, since deleting the post removes the redirect with it:
---
redirect_from:
- /old-post/
- /2020/01/hello.html
---Output and behavior
Each old address gets one HTML file, placed by the core's URL rules (/x/ becomes x/index.html, .html endings are kept as-is). The page carries rel=canonical pointing at the new address and robots: noindex,follow — search engines update their indexes instead of collecting duplicate pages.
Old addresses are normalized first (leading slash added, query and hash stripped, /x treated as /x/), so you don't need to worry about the exact format.
Notes
- If a real page already exists at an old address, the plugin skips it with a warning — it never overwrites real content
- To temporarily disable redirects on one post, set
redirect: falsein its front-matter - Redirect pages solve "people can still find the content"; for search-engine weight transfer, pair it with the canonical output of the
seoplugin. This kind of migration is exactly the plugin's use case when retiring old posts — URL rules are covered in content organization
Comments