f5792c40be
Pulled ALL skills from 15 source repositories: - anthropics/skills: 16 (docs, design, MCP, testing) - obra/superpowers: 14 (TDD, debugging, agents, planning) - coreyhaines31/marketingskills: 25 (marketing, CRO, SEO, growth) - better-auth/skills: 5 (auth patterns) - vercel-labs/agent-skills: 5 (React, design, Vercel) - antfu/skills: 16 (Vue, Vite, Vitest, pnpm, Turborepo) - Plus 13 individual skills from various repos Mosaic Stack is not limited to coding — the Orchestrator and subagents serve coding, business, design, marketing, writing, logistics, analysis, and more. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
170 lines
3.6 KiB
Markdown
170 lines
3.6 KiB
Markdown
---
|
|
name: vitepress-routing
|
|
description: File-based routing, source directory structure, clean URLs, and route rewrites
|
|
---
|
|
|
|
# Routing
|
|
|
|
VitePress uses file-based routing where markdown files map directly to HTML pages.
|
|
|
|
## File to URL Mapping
|
|
|
|
```
|
|
.
|
|
├─ index.md → /index.html (/)
|
|
├─ about.md → /about.html
|
|
├─ guide/
|
|
│ ├─ index.md → /guide/index.html (/guide/)
|
|
│ └─ getting-started.md → /guide/getting-started.html
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├─ docs # Project root
|
|
│ ├─ .vitepress # VitePress directory
|
|
│ │ ├─ config.ts # Configuration
|
|
│ │ ├─ theme/ # Custom theme
|
|
│ │ ├─ cache/ # Dev server cache (gitignore)
|
|
│ │ └─ dist/ # Build output (gitignore)
|
|
│ ├─ public/ # Static assets (copied as-is)
|
|
│ ├─ index.md # Home page
|
|
│ └─ guide/
|
|
│ └─ intro.md
|
|
```
|
|
|
|
## Source Directory
|
|
|
|
Separate source files from project root:
|
|
|
|
```ts
|
|
// .vitepress/config.ts
|
|
export default {
|
|
srcDir: './src' // Markdown files live in ./src/
|
|
}
|
|
```
|
|
|
|
With `srcDir: 'src'`:
|
|
|
|
```
|
|
.
|
|
├─ .vitepress/ # Config stays at project root
|
|
└─ src/ # Source directory
|
|
├─ index.md → /
|
|
└─ guide/intro.md → /guide/intro.html
|
|
```
|
|
|
|
## Linking Between Pages
|
|
|
|
Use relative or absolute paths. Omit file extensions:
|
|
|
|
```md
|
|
<!-- Recommended -->
|
|
[Getting Started](./getting-started)
|
|
[Guide](/guide/)
|
|
|
|
<!-- Works but not recommended -->
|
|
[Getting Started](./getting-started.md)
|
|
[Getting Started](./getting-started.html)
|
|
```
|
|
|
|
## Clean URLs
|
|
|
|
Remove `.html` extension from URLs (requires server support):
|
|
|
|
```ts
|
|
export default {
|
|
cleanUrls: true
|
|
}
|
|
```
|
|
|
|
**Server requirements:**
|
|
- Netlify, GitHub Pages: Supported by default
|
|
- Vercel: Enable `cleanUrls` in `vercel.json`
|
|
- Nginx: Configure `try_files $uri $uri.html $uri/ =404`
|
|
|
|
## Route Rewrites
|
|
|
|
Customize the mapping between source and output paths:
|
|
|
|
```ts
|
|
export default {
|
|
rewrites: {
|
|
// Static mapping
|
|
'packages/pkg-a/src/index.md': 'pkg-a/index.md',
|
|
'packages/pkg-a/src/foo.md': 'pkg-a/foo.md',
|
|
|
|
// Dynamic parameters
|
|
'packages/:pkg/src/:slug*': ':pkg/:slug*'
|
|
}
|
|
}
|
|
```
|
|
|
|
This maps `packages/pkg-a/src/intro.md` → `/pkg-a/intro.html`.
|
|
|
|
**Important:** Relative links in rewritten files should be based on the rewritten path, not the source path.
|
|
|
|
Rewrites can also be a function:
|
|
|
|
```ts
|
|
export default {
|
|
rewrites(id) {
|
|
return id.replace(/^packages\/([^/]+)\/src\//, '$1/')
|
|
}
|
|
}
|
|
```
|
|
|
|
## Public Directory
|
|
|
|
Files in `public/` are copied to output root as-is:
|
|
|
|
```
|
|
docs/public/
|
|
├─ favicon.ico → /favicon.ico
|
|
├─ robots.txt → /robots.txt
|
|
└─ images/logo.png → /images/logo.png
|
|
```
|
|
|
|
Reference with absolute paths:
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
## Base URL
|
|
|
|
For sub-path deployment (e.g., GitHub Pages):
|
|
|
|
```ts
|
|
export default {
|
|
base: '/repo-name/'
|
|
}
|
|
```
|
|
|
|
All absolute paths are automatically prefixed with base. For dynamic paths in components, use `withBase`:
|
|
|
|
```vue
|
|
<script setup>
|
|
import { withBase } from 'vitepress'
|
|
</script>
|
|
|
|
<template>
|
|
<img :src="withBase('/logo.png')" />
|
|
</template>
|
|
```
|
|
|
|
## Key Points
|
|
|
|
- `index.md` files map to directory root (`/guide/` instead of `/guide/index`)
|
|
- Use paths without extensions in links for flexibility
|
|
- `srcDir` separates source from config
|
|
- `cleanUrls` removes `.html` but requires server support
|
|
- `rewrites` enables complex source structures with clean output URLs
|
|
|
|
<!--
|
|
Source references:
|
|
- https://vitepress.dev/guide/routing
|
|
- https://vitepress.dev/guide/asset-handling
|
|
-->
|