vitepress 使用 banner

这几天一直在写文档，想着给文档加一个全局通知类的东西，找到了一个全局公告，但是好像不是很满意效果，说实话，有一点难看。然后后来想起来了 vue 文档的横幅效果，还有原神地图文档的那个横幅，说干就干，直接翻源码

源码是翻到了，vue 组件都是在 theme/components 目录下面,非常好找，在 vitepress 中全局组件都会在 theme/index.ts 内注册为全局组件。先看 vue 文档的,好巧不巧，官方文档注释掉了，继续翻中文版本的

1
import { h, App } from 'vue'
2
// import Banner from './components/Banner.vue'
3

4
export default Object.assign({}, VPTheme, {
5
  Layout: () => {
6
    // @ts-ignore
7
    return h(VPTheme.Layout, null, {
8
      // banner: () => h(Banner),
9
      'sidebar-top': () => h(PreferenceSwitch),
10
      'sidebar-bottom': () => h(SecurityUpdateBtn),
11
      'aside-mid': () => h(SponsorsAside)
12
    })
13
  },
14
  ...
15
}

vuejs-translations

docs-zh-cn

Waiting for api.github.com...

00K

Waiting...

也是又找到了翻译后的副本，好在并没有注释掉，直接 copy 过来，Banner.vue 组件也有一点变化，直接copy,

1
// import DefaultTheme from "vitepress/theme";
2
import DefaultTheme from "vitepress/theme-without-fonts";
9 collapsed lines
3
import {
4
    defineAsyncComponent,
5
    defineComponent,
6
    inject,
7
    nextTick,
8
    onMounted,
9
    watch,
10
    h,
11
} from "vue";
12
 import ArticleShare from "./components/ArticleShare.vue";
13

14
export default {
15
    extends: DefaultTheme,
16

17
    Layout() {
18
        return h(
26 collapsed lines
19
            NConfigProvider,
20
            { abstract: true, inlineThemeDisabled: true },
21
            {
22
                default: () => [
23
                    // 使用自定义MyLayout
24
                    h(MyLayout, null, {
25
                        "layout-top": () => [
26
                            h(UnderConstructionBanner),
27
                            h(NolebaseHighlightTargetedHeading),
28
                            h(Mouse),
29
                        ],
30
                        "doc-footer-before": () => h(backtotop),
31
                        // 在导航栏内容后面添加增强可读性菜单
32
                        "nav-bar-content-after": () => [
33
                            h(NolebaseEnhancedReadabilitiesMenu),
34
                        ],
35
                        // 在屏幕导航内容后面添加增强可读性菜单
36
                        "nav-screen-content-after": () =>
37
                            h(NolebaseEnhancedReadabilitiesScreenMenu),
38
                        // 在侧边栏导航前面添加鼠标切换
39
                        "sidebar-nav-before": () => h(MouseToggle),
40
                        // 在侧边栏导航后面添加音乐播放器
41
                        "sidebar-nav-after": () => h(Music),
42
                        // 在侧边栏下方添加分享按钮（使用包装组件解决 SSR 问题）
43
                        // "aside-outline-after": () => h(ArticleShare),
44

45
                        // 在布局顶部添加其他组件
46
                       "Banner": () => h(Banner),
47
                        "aside-top": () => [h(Carousel), h(ArticleShare)],
48
                    }),
49
                ],
50
            },
51
        );
52
    },
53
}
54

55
    ...

copy 是 copy 过来了，vitepress 开发环境也是没有报错，但是浏览器并没有渲染出来，继续找原因，又去看了一眼 vitepress 文档中的布局插槽。欸，不对，好像文档中没有 Banner 这个插槽。看了一眼 package.json 中的版本号。此时我文档使用的是 2.0-alpha5 版本，可能该插槽被弃用了

1
{
2
  "license": "CC BY-NC-SA 4.0",
10 collapsed lines
3
  "engines": {
4
    "node": ">=18.0.0",
5
    "pnpm": ">=7.4.0"
6
  },
7
  "type": "module",
8
  "scripts": {
9
    "dev": "vitepress",
10
    "build": "vitepress build",
11
    "preview": "vitepress preview",
12
  },
13
  "dependencies": {
14
    "@vue/repl": "^4.4.2",
15
    "@vue/theme": "^2.3.0",
16
    "dynamics.js": "^1.1.5",
17
    "gsap": "^3.12.5",
18
    "vitepress": "^1.4.3",
19
    "vue": "^3.5.12"
20
  },
21
  "devDependencies",
22
}

然后又去看了原神地图的文档内容，也是又翻到了,作为布局插槽插入到了 layout-top，组件有点难 copy ，干脆自己写一个。

kongying-tavern

docs

Waiting for api.github.com...

00K

Waiting...

1
<template>
2
  <Layout :class="{ [frontmatter.layout || '']: true, [frontmatter.class || '']: true }">
3
    <template #layout-top>
4
      <Banner />
5
      <Sonner />
6
    </template>
7

25 collapsed lines
8
    <template #doc-after>
9
      <DocReaction ref="target" />
10
    </template>
11

12
    <template #doc-before>
13
      <DocHeader />
14
    </template>
15
    <!--
16
    <template #doc-footer-before>
17
      <DocInfo />
18
    </template> -->
19

20
    <template #aside-outline-after>
21
      <DocAside v-if="showAside" :show-reaction="!targetIsVisible" />
22
    </template>
23

24
    <template #nav-bar-content-after>
25
      <NavBarUserAvatar />
26
    </template>
27

28
    <template #layout-bottom>
29
      <HighlightTargetedHeading />
30
      <Notifications />
31
    </template>
32
  </Layout>
33
</template>

终于，Banner 也是做出来了，作为布局插槽插入到了layout-top，渲染好像不太正常，当组件被插入到layout-top时，整个 navbar 会被往下压，进而导致 sidebar 和 aside 往下压。navbar logo 部分和 sidebar 部分内容直接就重叠了，可以说效果非常不好，然后又去看了一遍原神地图的文档，发现 Banner 的每个页面都没有 sidebar

所以这个方案也失败了，只能说无法用到我的文档里面，于是乎，去翻了 vitepress 的 issue ，还真找到了

Add support of Global Notification

看完整个 issue 之后发现，官方可能支持了，但是作为实验性，后续移除了，但是这个哥们留下的链接对我确实有点用

于是我又去翻了 oxc 的文档，顶部的 Banner 确实有

1
import type { Theme } from "vitepress";
2
import DefaultTheme from "vitepress/theme";
3
import { defineAsyncComponent, h } from "vue";
4
import Alert from "./components/Alert.vue";
5
import AppBadgeList from "./components/AppBadgeList.vue";
6
import AppBlogPostHeader from "./components/AppBlogPostHeader.vue";
7
import "virtual:group-icons.css";
8

9
export default {
10
  extends: DefaultTheme,
11
  async enhanceApp({ app }) {
12
    app.component("AppBadgeList", AppBadgeList);
13
    app.component("AppBlogPostHeader", AppBlogPostHeader);
14
    app.component("Alert", Alert);
15
  },
16
  Layout() {
17
    return h(DefaultTheme.Layout, null, {
18
      "layout-top": () => h(defineAsyncComponent(() => import("./components/Banner.vue"))),
19
    });
20
  },
21
} satisfies Theme;

到这里差不多就解决了，还是使用 layout-top 这个插槽，但是注册方式不太一样，这里使用了 defineAsyncComponent 去加载这个组件，至此，加上之前 vue 文档获取的组件，彻底完结，最后看看效果

记录一次 Vitepress 使用 Banner#