用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/fabioc-aloha/Alex_Skill_Mall --skill vitepress-iframe-embed命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | vitepress-iframe-embed |
| description | VitePress iframe embedding gotchas — CSP headers, sandboxing, responsive sizing |
| lastReviewed | 2026-04-30T00:00:00.000Z |
Category: VitePress Time Saved: 1 hour debugging SPA routing Battle-tested: Yes — embedding standalone HTML in VitePress sites
You have a standalone HTML application (a dashboard, interactive tool, or legacy page) that you want to include in your VitePress documentation site. You add a link in the nav, but clicking it either shows a blank page or VitePress intercepts the navigation.
VitePress is a Single Page Application (SPA). It intercepts all navigation clicks to provide smooth page transitions. When you link to a non-VitePress HTML file, the SPA router doesn't know what to do with it.
Use the iframe embed pattern: Create a .md page with a Vue component that embeds your HTML via iframe.
<!-- docs/tools/dashboard.md -->
---
title: Dashboard
---
<DashboardEmbed />
<!-- docs/.vitepress/components/DashboardEmbed.vue -->
<template>
<div class="embed-container">
<iframe
:src="iframeSrc"
frameborder="0"
class="embed-frame"
/>
</div>
</template>
<script setup>
import { computed } from 'vue'
const iframeSrc = computed(() => {
// Add ?embed query param for the HTML to detect
return '/tools/dashboard.html?embed'
})
</script>
<style scoped>
.embed-container {
width: 100%;
height: calc(100vh - 200px);
min-height: 500px;
}
.embed-frame {
width: 100%;
height: 100%;
border: none;
}
</style>
// docs/.vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import DashboardEmbed from '../components/DashboardEmbed.vue'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
app.component('DashboardEmbed', DashboardEmbed)
}
}
<!-- public/tools/dashboard.html -->
<!DOCTYPE html>
<html>
<head>
<style>
/* Hide chrome when embedded */
.embed-mode header,
.embed-mode footer,
.embed-mode .nav { display: none; }
.embed-mode main { padding: 0; margin: 0; }
</style>
</head>
<body>
<header>...</header>
<main>...</main>
<footer>...</footer>
<script>
// Detect embed mode from URL
if (window.location.search.includes('embed')) {
document.body.classList.add('embed-mode');
}
If you don't need seamless integration, use target="_self":
// docs/.vitepress/config.js
export default {
themeConfig: {
nav: [
{ text: 'Dashboard', link: '/tools/dashboard.html', target: '_self' }
]
}
}
This forces a full page navigation, bypassing the SPA router.
Iframes cannot access parent CSS custom properties. If your embedded HTML uses VitePress CSS variables, provide fallbacks:
/* In embedded HTML */
:root {
--vp-c-brand: #646cff; /* Fallback, not inherited */
}
// docs/.vitepress/config.js
export default {
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Docs', link: '/guide/' },
{ text: 'Dashboard', link: '/tools/dashboard' } // Points to .md wrapper
]
}
}
docs/
.vitepress/
components/
DashboardEmbed.vue
theme/
index.js
config.js
tools/
dashboard.md # Wrapper page
public/
tools/
dashboard.html # Actual HTML app
.md page created?embed and hides chromegithub-wiki-flat — Similar link rewriting issues