القائمة
VitePress iframe embedding gotchas — CSP headers, sandboxing, responsive sizing
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/fabioc-aloha/Alex_Skill_Mall --skill vitepress-iframe-embedيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
Create or improve a Markdown instruction, skill, prompt, or agent from an explicitly selected file or user-identified text. Use when a user asks to optimize an existing brain artifact or create one for consistent future execution.
Clear documentation through visual excellence
Assess active Markdown brain files in a local AI agent project or plugin source without changing it. Use before modifying a brain or reviewing declared instructions, skills, prompts, agents, bundled Markdown resources, and research documentation.
استنادا إلى تصنيف 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