fix: 修改文档自定义 ui

.gitignore

@@ -8,7 +8,6 @@ node_modules
 #build
 /dist/
 /dist-doc-only/
-/dist-doc-embedded/
 
 # CI/本地经 downloadFile.js 下载生成的 Agent 配置页(downloadFile.json)
 /docs/07-configuration/
@@ -17,7 +16,7 @@ node_modules
 # vitepress
 .vitepress/cache/
 /cache/
-
-# Local preview and design files
-/.impeccable.md
-/docs/zh/markdown-style-preview.md
+
+# Local preview and design files
+/.impeccable.md
+/docs/zh/markdown-style-preview.md

.vitepress/config.mts

@@ -11,15 +11,13 @@ import { legacyLinks } from './markdown/legacy-links'
 const GITHUB_DOCS = 'https://github.com/deepflowio/docs'
 
 // 构建变体(由 package.json 的 dev:doc-only / build:doc-only /
-// preview:doc-only 注入 DOCS_MODE=doc-only;产品内嵌模式为 doc-embedded):
+// preview:doc-only 注入 DOCS_MODE=doc-only):
 //   默认    —— 供主站嵌入,全站导航栏/页脚始终隐藏(产物 dist);
 //   doc-only —— 独立文档站,渲染 doc 专属顶栏(DocHeader)、无页脚
-//              (产物 dist-doc-only);
-//   doc-embedded —— 产品内嵌文档,无 Logo/站名,搜索位于左侧,正文顶距 32px
-//              (产物 dist-doc-embedded)。差异均由构建期写进 head 的
-//              html 类标记驱动,见下方 head 与 theme/custom.css
+//              (产物 dist-doc-only)。产品内嵌同一份产物:页面在 iframe
+//              中打开时 head 脚本标记 embedded,custom.css 据此去掉
+//              顶栏品牌区并把搜索移到左侧(见下方 head 与 theme/custom.css)
 const DOC_ONLY = process.env.DOCS_MODE === 'doc-only'
-const DOC_EMBEDDED = process.env.DOCS_MODE === 'doc-embedded'
 
 export default withMermaid(
   defineConfig({
@@ -31,8 +29,8 @@ export default withMermaid(
     srcDir: 'docs',
     // 产物输出到仓库根 dist(默认是 .vitepress/dist),与 Dockerfile 的 COPY ./dist
     // 及 df-help 企业版 CI 的 mv ./docs/dist/* 对齐;doc-only 变体单独输出到
-    // dist-doc-only / dist-doc-embedded,避免不同形态互相覆盖
-    outDir: DOC_EMBEDDED ? 'dist-doc-embedded' : DOC_ONLY ? 'dist-doc-only' : 'dist',
+    // dist-doc-only,避免两种形态互相覆盖
+    outDir: DOC_ONLY ? 'dist-doc-only' : 'dist',
     base: '/docs/',
     // 主题默认 dark(旧站观感)。'dark' 下 VitePress 优先读 localStorage
     // (vitepress-theme-appearance),无记录时回退此默认值,切换时写回;
@@ -103,21 +101,19 @@ export default withMermaid(
       ['meta', { name: 'theme-color', content: '#0a72ef' }],
       // html 类标记(内联在 head 中于首帧前执行,无闪烁),配合
       // theme/custom.css 控制全站 chrome 的显隐:
-      //   - embedded:隐藏全站导航栏/页脚(SiteNavbar/SiteFooter)并清空其
-      //     占位。首行的 iframe 检测保留(参考 eaf3930)——后续若恢复
-      //     "仅 iframe 嵌入时隐藏"的策略,删掉下方无条件标记即可;
-      //     目前常规构建也始终隐藏
-      //   - doc-only:独立站与产品内嵌变体共用,恢复 doc 专属顶栏(DocHeader)
-      //     的高度占位,页脚保持隐藏
-      //   - doc-embedded:产品内嵌变体添加,在共用布局上调整品牌区和间距
+      //   - embedded:真实 iframe 环境(head 首行检测,参考 eaf3930)。常规
+      //     构建供主站嵌入、无论如何都隐藏全站导航栏/页脚,故额外无条件
+      //     标记;doc-only 构建则只在真的嵌入 iframe(产品内嵌文档)时
+      //     带上此类,custom.css 据此微调 doc 专属顶栏
+      //   - doc-only:doc-only 变体添加,恢复 doc 专属顶栏(DocHeader)的
+      //     高度占位,页脚保持隐藏
       [
         'script',
         {},
         [
           "if (window.self !== window.top) document.documentElement.classList.add('embedded');",
-          "document.documentElement.classList.add('embedded');",
-          DOC_ONLY || DOC_EMBEDDED ? "document.documentElement.classList.add('doc-only');" : '',
-          DOC_EMBEDDED ? "document.documentElement.classList.add('doc-embedded');" : ''
+          DOC_ONLY ? '' : "document.documentElement.classList.add('embedded');",
+          DOC_ONLY ? "document.documentElement.classList.add('doc-only');" : ''
         ]
           .filter(Boolean)
           .join('')

.vitepress/theme/components/DocBreadcrumb.vue

@@ -61,7 +61,6 @@ const parents = computed(() => crumbs.value.slice(0, -1))
   max-width: var(--df-md-reading-width);
   margin: 0 auto 28px;
   color: var(--df-md-text-3);
-  font-family: var(--df-md-font-sans);
   font-size: 13px;
   line-height: 1.6;
   overflow-wrap: anywhere;

.vitepress/theme/components/DocHeader.vue

@@ -93,13 +93,14 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue'
-import { useData, useRouter } from 'vitepress'
-import darkLogo from '../assets/docs-logo-dark.png'
-import lightLogo from '../assets/docs-logo-light.png'
+import { useData, useRouter, withBase } from 'vitepress'
 
 const { lang, site, isDark } = useData()
 const router = useRouter()
 const base = site.value.base // '/docs/'
+// 深色图案用于浅色主题,浅色图案用于深色主题(统一存放于 public/img)
+const darkLogo = withBase('/img/docs-logo-dark.png')
+const lightLogo = withBase('/img/docs-logo-light.png')
 
 const isZh = computed(() => lang.value?.startsWith('zh'))
 const currentType = computed(() => (isZh.value ? 'zh' : 'en'))

.vitepress/theme/custom.css

@@ -34,13 +34,13 @@
 
 /* ===== embedded:全站 chrome 隐藏(参考 eaf3930) =====
    <html> 带 embedded 类时隐藏全站导航栏(SiteNavbar)/页脚(SiteFooter)
-   并清空其占位间距;移动端以内容区左上角的悬浮按钮
-   (EmbeddedSidebarButton,doc-top 插槽)展开侧边栏。
-   该类由 head 内联脚本标记(见 config.mts):iframe 检测保留,但目前
-   常规构建也无条件标记,即导航栏/页脚始终隐藏;doc-only 变体在此基础上
-   通过 doc-only 类恢复 doc 专属顶栏(见下方 doc-only 段) */
-html.embedded .df-navbar,
-html.embedded .df-footer {
+   并清空其占位间距;移动端以面包屑同行的目录按钮
+   (EmbeddedSidebarButton,doc-before 插槽)展开侧边栏。
+   该类由 head 内联脚本标记(见 config.mts):常规构建无条件标记(主站
+   嵌入形态,始终隐藏);doc-only 变体仅在真实 iframe 环境(产品内嵌
+   文档)标记,独立访问时不带此类,导航栏/页脚由下方 doc-only 段隐藏 */
+html:is(.embedded, .doc-only) .df-navbar,
+html:is(.embedded, .doc-only) .df-footer {
   display: none;
 }
 html.embedded {
@@ -49,8 +49,9 @@ html.embedded {
   --df-nav-height-mobile: 0px;
 }
 /* 嵌入式下隐藏"菜单"吸顶条:桌面端侧边栏常驻可见无需它,
-   移动端由悬浮按钮承担(该条隐藏后其菜单按钮仍在 DOM 中,供程序化点击) */
-html.embedded .VPLocalNav {
+   移动端由目录按钮承担(该条隐藏后其菜单按钮仍在 DOM 中,供程序化点击)。
+   doc-only 变体同样隐藏,保持独立站与产品内嵌一致的观感 */
+html:is(.embedded, .doc-only) .VPLocalNav {
   display: none;
 }
 /* 嵌入式桌面端导航高度归零后侧边栏内容会顶到视口边缘,
@@ -69,21 +70,23 @@ html.embedded .Layout .VPHero.VPHero {
   html.embedded .VPContent {
     padding-top: 48px;
   }
-  html.embedded .embedded-sidebar-button {
+  html:is(.embedded, .doc-only) .embedded-sidebar-button {
     display: flex;
   }
   /* 侧边栏展开后隐藏按钮,通过点击蒙层关闭 */
-  html.embedded:has(.VPSidebar.open) .embedded-sidebar-button {
+  html:is(.embedded, .doc-only):has(.VPSidebar.open) .embedded-sidebar-button {
     display: none;
   }
 }
 
 /* ===== doc-only 变体(build:doc-only,独立文档站形态) =====
-   该形态下 <html> 同时带 embedded 与 doc-only 类(构建期写死,见
-   config.mts 的 head 脚本):复用上方 embedded 的导航栏/页脚隐藏与占位
-   清零,页脚保持隐藏;doc 专属顶栏(DocHeader,layout-top 插槽)为固定
+   该形态下 <html> 带 doc-only 类(构建期写死,见 config.mts 的 head
+   脚本):站点导航栏/页脚的隐藏已并入上方 embedded 段(:is 选择器),
+   页脚保持隐藏;doc 专属顶栏(DocHeader,layout-top 插槽)为固定
    定位,其高度写回 --vp-nav-height / --df-nav-height-mobile 后,内容区/
-   侧边栏/首页 hero 的顶部留白机制与 SiteNavbar 在位时一致 */
+   侧边栏/首页 hero 的顶部留白机制与 SiteNavbar 在位时一致。
+   产品内嵌同一份产物:页面在 iframe 中打开时 head 脚本追加 embedded
+   类,顶栏去掉品牌区、搜索移到左侧(见本段末尾) */
 html.doc-only {
   --df-doc-header-height: 64px;
   --vp-nav-height: var(--df-doc-header-height);
@@ -132,6 +135,22 @@ html.doc-only .sidebar-actions {
   }
 }
 
+/* ===== 产品内嵌(doc-only 产物在 iframe 中打开) =====
+   embedded 类由 head 内联脚本在真实 iframe 环境下添加(首帧前,无闪烁):
+   顶栏去掉 Logo/站名,搜索从居中移到左侧 */
+html.doc-only.embedded .doc-header .doc-brand {
+  display: none;
+}
+
+html.doc-only.embedded .doc-header .doc-header-inner {
+  grid-template-columns: minmax(0, 1fr) auto;
+}
+
+html.doc-only.embedded .doc-header .doc-search-trigger {
+  justify-self: start;
+  width: min(320px, 100%);
+}
+
 /* ===== 首页:对齐旧版 vdoing Home 布局 =====
    覆盖默认主题组件的 scoped 样式,选择器多带一层祖先保证优先级 */
 .VPHero .container {
@@ -209,3 +228,8 @@ html.doc-only .sidebar-actions {
 .vp-doc .mermaid svg {
   max-width: 100%;
 }
+
+
+.medium-zoom-overlay, .medium-zoom-image--opened {
+  z-index: 100;
+}