vitepress-spa-routing

name	vitepress-spa-routing
description	VitePress intercepts all navigation clicks for SPA routing:
lastReviewed	2026-04-30T00:00:00.000Z

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

1. Click the link
2. Browser should do full page load (network tab shows document request)
3. 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