gabrielmoreira VitePress SPA Routing
The Problem
VitePress intercepts all navigation clicks for SPA routing:
<!-- This link will be handled by VitePress router -->
<a href="/external-app/">External App</a>
<!-- VitePress fetches /external-app/index.md instead of navigating -->
This breaks:
- Links to non-VitePress pages in the same domain
- Links to static HTML files
- Links to other apps hosted at subpaths
The Solution
Option 1: target="_self" (Force Full Navigation)
// In .vitepress/config.js
nav: [
{
text: 'External App',
link: '/app/',
target: '_self' // Forces full page navigation
}
]
Option 2: External Link
nav: [
{
text: 'External App',
link: 'https://same-domain.com/app/' // Full URL bypasses router
}
]
Option 3: Iframe Embed (See vitepress-iframe-embed skill)
For standalone HTML that should appear within VitePress layout.
When Each Applies
| Scenario | Solution |
|---|---|
| Link to different app on same domain | target: "_self" |
| Link to truly external site | Full URL |
| Embed external content in VitePress layout | Iframe pattern |
| Link to static HTML file | target: "_self" |
In Markdown
<!-- Bad: VitePress intercepts -->
[Go to app](/app/)
<!-- Good: Force navigation -->
<a href="/app/" target="_self">Go to app</a>
<!-- Also good: Full URL -->
[Go to app](https://example.com/app/)
Verification
- Click the link
- Browser should do full page load (network tab shows document request)
- URL bar shows target URL (not VitePress route)
When to Apply
- Multi-app deployments on same domain
- Static HTML files alongside VitePress
- Links to server-rendered pages
Tags
vitepress spa routing navigation