feat(theme): add `home-hero-image` slot (#1528)

Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>

docs/guide/theme-introduction.md

@@ -212,6 +212,7 @@ Full list of slots available in the default theme layout:
   - `aside-ads-after`
 - When `layout: 'home'` is enabled via frontmatter:
   - `home-hero-before`
+  - `home-hero-image`
   - `home-hero-after`
   - `home-features-before`
   - `home-features-after`

src/client/theme-default/Layout.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { provide, watch } from 'vue'
+import { computed, provide, useSlots, watch } from 'vue'
 import { useData, useRoute } from 'vitepress'
 import { useSidebar, useCloseSidebarOnEscape } from './composables/sidebar.js'
 import VPSkipLink from './components/VPSkipLink.vue'
@@ -25,6 +25,11 @@ provide('close-sidebar', closeSidebar)
 provide('is-sidebar-open', isSidebarOpen)
 
 const { frontmatter } = useData()
+
+const slots = useSlots()
+const heroImageSlotExists = computed(() => !!slots['home-hero-image'])
+
+provide('hero-image-slot-exists', heroImageSlotExists)
 </script>
 
 <template>
@@ -49,6 +54,7 @@ const { frontmatter } = useData()
 
     <VPContent>
       <template #home-hero-before><slot name="home-hero-before" /></template>
+      <template #home-hero-image><slot name="home-hero-image" /></template>
       <template #home-hero-after><slot name="home-hero-after" /></template>
       <template #home-features-before><slot name="home-features-before" /></template>
       <template #home-features-after><slot name="home-features-after" /></template>

src/client/theme-default/components/VPContent.vue

@@ -28,6 +28,7 @@ const NotFound = inject('NotFound')
 
     <VPHome v-else-if="frontmatter.layout === 'home'">
       <template #home-hero-before><slot name="home-hero-before" /></template>
+      <template #home-hero-image><slot name="home-hero-image" /></template>
       <template #home-hero-after><slot name="home-hero-after" /></template>
       <template #home-features-before><slot name="home-features-before" /></template>
       <template #home-features-after><slot name="home-features-after" /></template>

src/client/theme-default/components/VPHero.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { Ref, inject } from 'vue'
 import type { DefaultTheme } from 'vitepress/theme'
 import VPButton from './VPButton.vue'
 import VPImage from './VPImage.vue'
@@ -16,10 +17,12 @@ defineProps<{
   image?: DefaultTheme.ThemeableImage
   actions?: HeroAction[]
 }>()
+
+const heroImageSlotExists = inject('hero-image-slot-exists') as Ref<boolean>
 </script>
 
 <template>
-  <div class="VPHero" :class="{ 'has-image': image }">
+  <div class="VPHero" :class="{ 'has-image': image || heroImageSlotExists }">
     <div class="container">
       <div class="main">
         <h1 v-if="name" class="name">
@@ -41,10 +44,12 @@ defineProps<{
         </div>
       </div>
 
-      <div v-if="image" class="image">
+      <div v-if="image || heroImageSlotExists" class="image">
         <div class="image-container">
           <div class="image-bg" />
-          <VPImage class="image-src" :image="image" />
+          <slot name="home-hero-image">
+            <VPImage v-if="image" class="image-src" :image="image" />
+          </slot>
         </div>
       </div>
     </div>

src/client/theme-default/components/VPHome.vue

@@ -6,7 +6,9 @@ import VPHomeFeatures from './VPHomeFeatures.vue'
 <template>
   <div class="VPHome">
     <slot name="home-hero-before" />
-    <VPHomeHero />
+    <VPHomeHero>
+      <template #home-hero-image><slot name="home-hero-image" /></template>
+    </VPHomeHero>
     <slot name="home-hero-after" />
 
     <slot name="home-features-before" />

src/client/theme-default/components/VPHomeHero.vue

@@ -14,5 +14,7 @@ const { frontmatter: fm } = useData()
     :tagline="fm.hero.tagline"
     :image="fm.hero.image"
     :actions="fm.hero.actions"
-  />
+  >
+    <template #home-hero-image><slot name="home-hero-image" /></template>
+  </VPHero>
 </template>