A powerful client-side redirection plugin for VitePress that generates static redirect pages and handles seamless navigation between old and new URLs.
- 🔄 Client-side redirects - Fast, seamless navigation without server configuration
- 📄 Static redirect pages - Generates HTML files for each redirect during build
- 🎨 Custom templates - Use your own redirect page design or stick with the beautiful default
- ⚡ Zero JavaScript fallback - Works even with JavaScript disabled via meta refresh
- 🔍 SEO friendly - Proper meta tags, canonical links, and no-index options
- 🛡️ Validation - Detects circular redirects, conflicts, and dead links
- ⚙️ Flexible configuration - Simple redirect maps or advanced options
pnpm add -D @itznotabug/routexAdd routex to your VitePress configuration:
// .vitepress/config.ts
import { routex } from 'routex'
import { defineConfig } from 'vitepress'
export default defineConfig({
// ... your VitePress config
vite: {
plugins: [
routex({
'/old-page': '/new-page',
'/legacy/docs': '/docs',
'/api/v1': '/api/v2'
})
]
}
})Routex will automatically:
- Handle navigation seamlessly
- Inject client-side redirect scripts
- Generate redirect pages at build time
routex({
'/old-page': '/new-page',
'/legacy': '/modern',
'/blog/2023': '/blog/archive/2023'
})routex({
rules: {
'/old-api': '/api/v2',
'/docs/legacy': '/docs',
'/external-link': 'https://example.com'
},
options: {
redirectDelay: 2, // Delay in seconds (default: 0)
addCanonical: true, // Add canonical link tags (default: false)
addNoIndexMeta: true, // Add noindex meta tag (default: false)
template: './custom-redirect.html', // Custom template path
overrideExisting: false, // Allow overriding existing pages (default: false)
ignoreDeadLinks: false // Skip validation for missing destinations (default: false)
}
})Create a custom redirect template with placeholders:
<!-- custom-redirect.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Redirecting to {destination}</title>
{metaTags}
<style>
body {
font-family: system-ui;
text-align: center;
padding: 50px;
}
</style>
<script>
setTimeout(() => {
location.replace('{destination}');
}, {redirectDelay} * 1000);
</script>
</head>
<body>
<h1>🚀 Moving to a better place...</h1>
<p>You're being redirected from <code>{source}</code> to <code>{destination}</code></p>
<p><a href="{destination}">Click here if you're not redirected automatically</a></p>
</body>
</html>Available placeholders:
{source}- Original URL path{destination}- Target URL{redirectDelay}- Delay in seconds{metaTags}- Generated meta tags (refresh, canonical, noindex)
| Option | Type | Default | Description |
|---|---|---|---|
enable |
boolean |
true |
Enable/disable the plugin |
redirectDelay |
number |
0 |
Delay before redirect (seconds) |
addCanonical |
boolean |
false |
Add canonical link tags for SEO |
addNoIndexMeta |
boolean |
false |
Add noindex meta tag to prevent indexing |
template |
string |
'' |
Path to custom template or inline HTML |
overrideExisting |
boolean |
false |
Allow redirects to override existing pages |
ignoreDeadLinks |
boolean |
false |
Skip validation for missing destination pages |
Routex automatically validates your redirect configuration:
- Self-references - Detects redirects that point to themselves
- Circular redirects - Prevents infinite redirect loops
- Path validation - Ensures proper URL formatting
- File conflicts - Warns about redirects that override existing pages
- Dead links - Checks if destination pages exist
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Ensure tests pass:
pnpm test:run - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Built for VitePress - The amazing static site generator
- Continuous test releases via pkg-vc - Built by @Torsten Dittmann
⭐ Star this repo if you find it useful!