@voidzero-dev/vitepress-theme 4.5.1 → 4.7.0

package/README.md

@@ -4,14 +4,11 @@ Shared VitePress theme for VoidZero projects, including Vite+, Vite, Vitest, Rol
 
 ## Publishing package
 
-Make to sure to in latest commit
-
-1. Update version in `package.json` and commit it (don't push yet)
-2. Add tag locally `git tag vx.y.z` (matching version in package.json)
-3. Push changes `git push origin`
-4. Push to remote `git push origin vx.y.z`
-5. Go to GitHub UI > "Releases" > "Tags" > Click the latest tag > "Create release from tag"
-6. Click "Publish release"
+```bash
+pnpm release <version>  # e.g. pnpm release 4.6.1
+```
+
+This updates `package.json`, commits, tags, and pushes. CI publishes to npm and creates the GitHub release.
 
 ## Developing locally
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidzero-dev/vitepress-theme",
-  "version": "4.5.1",
+  "version": "4.7.0",
   "description": "Shared VitePress theme for VoidZero projects",
   "type": "module",
   "license": "UNLICENSED",
@@ -32,10 +32,14 @@
     "mark.js": "8.11.1",
     "minisearch": "^7.2.0",
     "reka-ui": "^2.5.1",
-    "tailwindcss": "^4.1.18"
+    "tailwindcss": "^4.1.18",
+    "@iconify/vue": "^5.0.0"
   },
   "devDependencies": {
     "@types/mark.js": "^8.11.12",
     "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "release": "node scripts/release.ts"
   }
 }

package/src/components/oss/FeatureGrid.vue

@@ -1,4 +1,5 @@
 <script setup>
+import { Icon } from '@iconify/vue'
 import { useData } from 'vitepress'
 
 const { frontmatter } = useData()
@@ -7,11 +8,12 @@ const { frontmatter } = useData()
 <template>
   <section v-if="frontmatter.features"
     class="wrapper wrapper--ticks border-t grid md:grid-cols-2 divide-x divide-y divide-nickel">
-    <div v-for="feature in frontmatter.features" :key="feature.icon"
+    <div v-for="feature in frontmatter.features" :key="feature.icon || feature.iconify"
       class="flex flex-col gap-3 justify-between border-r-0 md:odd:border-r md:nth-last-2:border-b-0">
       <div class="px-10 py-8 sm:px-15 sm:py-12 flex flex-col gap-3">
         <p class="text-2xl">
-          {{ feature.icon }}
+          <Icon v-if="feature.iconify" :icon="feature.iconify" width="1em" height="1em" />
+          <template v-else>{{ feature.icon }}</template>
         </p>
         <h5 class="text-balance sm:text-pretty text-white">
           {{ feature.title }}

package/src/components/oss/Hero.vue

@@ -1,6 +1,10 @@
-<script setup>
+<script setup lang="ts">
 import { useData } from 'vitepress'
 
+const props = defineProps<{
+  background?: string
+}>()
+
 const { frontmatter } = useData()
 </script>
 
@@ -27,9 +31,11 @@ const { frontmatter } = useData()
         </div>
       </div>
     </div>
-    <div class="flex flex-col">
+    <div class="flex flex-col bg-cover bg-center" :style="props.background ? { backgroundImage: `url(${props.background})` } : undefined">
       <div class="relative px-10 pb-10 md:pt-10 h-full flex flex-col justify-center overflow-clip">
-        <img :src="frontmatter.hero.image.src" :alt="frontmatter.hero.image.alt" class="max-h-[20rem]">
+        <slot name="hero-image">
+          <img v-if="frontmatter.hero.image?.src" :src="frontmatter.hero.image.src" :alt="frontmatter.hero.image.alt" class="max-h-[20rem]">
+        </slot>
       </div>
     </div>
   </div>

package/src/components/vitepress-default/VPFlyout.vue

@@ -1,16 +1,21 @@
 <script lang="ts" setup generic="T extends DefaultTheme.NavItem">
 import type { DefaultTheme } from 'vitepress/theme'
+import type { IconOption } from '../../types/theme-config'
 import { ref } from 'vue'
 import { useFlyout } from '@vp-composables/flyout'
+import { useIcon } from '@vp-composables/icon'
+import { Icon } from '@iconify/vue'
 import VPMenu from './VPMenu.vue'
 
-defineProps<{
-  icon?: string
+const props = defineProps<{
+  icon?: IconOption
   button?: string
   label?: string
   items?: T[]
 }>()
 
+const resolvedIcon = useIcon(() => props.icon)
+
 const open = ref(false)
 const el = ref<HTMLElement>()
 
@@ -36,8 +41,8 @@ function onBlur() {
       :aria-label="label"
       @click="open = !open"
     >
-      <span v-if="button || icon" class="flex items-center gap-1 leading-normal overflow-hidden">
-        <span v-if="icon" :class="icon" class="shrink-0" />
+      <span v-if="button || resolvedIcon" class="flex items-center gap-1 leading-normal overflow-hidden">
+        <Icon v-if="resolvedIcon" :icon="resolvedIcon" class="shrink-0 mr-0.5" />
         <span v-if="button" v-html="button" class="overflow-hidden text-ellipsis"></span>
         <span class="vpi-chevron-down text-sm shrink-0" />
       </span>
@@ -76,4 +81,8 @@ button[aria-expanded="true"] + .menu,
 .VPFlyout:hover .menu {
   display: block;
 }
+
+.VPFlyout.active button {
+  color: var(--vp-c-brand-1);
+}
 </style>

package/src/components/vitepress-default/VPMenuLink.vue

@@ -2,7 +2,9 @@
 import type { DefaultTheme } from 'vitepress/theme'
 import { computed } from 'vue'
 import { useData } from '@vp-composables/data'
+import { useIcon } from '@vp-composables/icon'
 import { isActive } from '../../support/vitepress-default/shared-utils'
+import { Icon } from '@iconify/vue'
 import VPLink from './VPLink.vue'
 
 const props = defineProps<{
@@ -12,6 +14,8 @@ const props = defineProps<{
 
 const { page } = useData()
 
+const icon = useIcon(() => props.item.icon)
+
 const href = computed(() =>
   typeof props.item.link === 'function'
     ? props.item.link(page.value)
@@ -38,6 +42,7 @@ defineOptions({ inheritAttrs: false })
       :rel="props.rel ?? item.rel"
       :no-icon="item.noIcon"
     >
+      <Icon v-if="icon" :icon="icon" class="shrink-0 mr-0.5" />
       <span v-html="item.text"></span>
     </VPLink>
   </div>

package/src/components/vitepress-default/VPNavBarMenuGroup.vue

@@ -36,6 +36,7 @@ const childrenActive = computed(() => isChildActive(props.item))
         isActive(page.relativePath, item.activeMatch, !!item.activeMatch) ||
         childrenActive
     }"
+    :icon="item.icon"
     :button="item.text"
     :items="item.items"
   />

package/src/components/vitepress-default/VPNavBarMenuLink.vue

@@ -2,7 +2,9 @@
 import type { DefaultTheme } from 'vitepress/theme'
 import { computed } from 'vue'
 import { useData } from '@vp-composables/data'
+import { useIcon } from '@vp-composables/icon'
 import { isActive } from '../../support/vitepress-default/shared-utils'
+import { Icon } from '@iconify/vue'
 import VPLink from './VPLink.vue'
 
 const props = defineProps<{
@@ -11,6 +13,8 @@ const props = defineProps<{
 
 const { page } = useData()
 
+const icon = useIcon(() => props.item.icon)
+
 const href = computed(() =>
   typeof props.item.link === 'function'
     ? props.item.link(page.value)
@@ -20,7 +24,7 @@ const href = computed(() =>
 
 <template>
   <VPLink
-    class="flex items-center px-3 py-2 text-base font-heading text-primary
+    class="flex items-center gap-1 px-3 py-2 text-base font-heading text-primary
      dark:text-white hover:opacity-85 transition-opacity whitespace-nowrap overflow-hidden text-ellipsis"
     :class="{
       active: isActive(
@@ -29,6 +33,7 @@ const href = computed(() =>
         !!item.activeMatch
       )
     }" :href :target="item.target" :rel="item.rel" :no-icon="item.noIcon" tabindex="0">
+    <Icon v-if="icon" :icon="icon" class="shrink-0 mr-0.5" />
     <span v-html="item.text"></span>
   </VPLink>
 </template>

package/src/components/vitepress-default/VPNavScreenMenu.vue

@@ -19,6 +19,7 @@ const { theme } = useData()
       <VPNavScreenMenuGroup
         v-else
         :text="item.text || ''"
+        :icon="item.icon"
         :items="item.items"
       />
     </template>

package/src/components/vitepress-default/VPNavScreenMenuGroup.vue

@@ -1,13 +1,19 @@
 <script lang="ts" setup>
+import type { IconOption } from '../../types/theme-config'
 import { computed, ref } from 'vue'
+import { useIcon } from '@vp-composables/icon'
+import { Icon } from '@iconify/vue'
 import VPNavScreenMenuGroupLink from './VPNavScreenMenuGroupLink.vue'
 import VPNavScreenMenuGroupSection from './VPNavScreenMenuGroupSection.vue'
 
 const props = defineProps<{
   text: string
+  icon?: IconOption
   items: any[]
 }>()
 
+const resolvedIcon = useIcon(() => props.icon)
+
 const isOpen = ref(false)
 
 const groupId = computed(
@@ -27,7 +33,10 @@ function toggle() {
       :aria-expanded="isOpen"
       @click="toggle"
     >
-      <span class="button-text" v-html="text"></span>
+      <span class="flex items-center">
+        <Icon v-if="resolvedIcon" :icon="resolvedIcon" class="shrink-0 mr-0.5" />
+        <span class="button-text" v-html="text"></span>
+      </span>
       <span class="vpi-plus button-icon" />
     </button>
 

package/src/components/vitepress-default/VPNavScreenMenuGroupLink.vue

@@ -2,7 +2,9 @@
 import type { DefaultTheme } from 'vitepress/theme'
 import { computed, inject } from 'vue'
 import { useData } from '@vp-composables/data'
+import { useIcon } from '@vp-composables/icon'
 import { navInjectionKey } from '@vp-composables/nav'
+import { Icon } from '@iconify/vue'
 import VPLink from './VPLink.vue'
 
 const props = defineProps<{
@@ -11,6 +13,8 @@ const props = defineProps<{
 
 const { page } = useData()
 
+const icon = useIcon(() => props.item.icon)
+
 const href = computed(() =>
   typeof props.item.link === 'function'
     ? props.item.link(page.value)
@@ -29,13 +33,15 @@ const { closeScreen } = inject(navInjectionKey)!
     :no-icon="item.noIcon"
     @click="closeScreen"
   >
+    <Icon v-if="icon" :icon="icon" class="shrink-0 mr-0.5" />
     <span v-html="item.text"></span>
   </VPLink>
 </template>
 
 <style scoped>
 .VPNavScreenMenuGroupLink {
-  display: block;
+  display: flex;
+  align-items: center;
   margin-left: 12px;
   line-height: 32px;
   font-size: 14px;

package/src/components/vitepress-default/VPNavScreenMenuLink.vue

@@ -2,7 +2,9 @@
 import type { DefaultTheme } from 'vitepress/theme'
 import { computed, inject } from 'vue'
 import { useData } from '@vp-composables/data'
+import { useIcon } from '@vp-composables/icon'
 import { navInjectionKey } from '@vp-composables/nav'
+import { Icon } from '@iconify/vue'
 import VPLink from './VPLink.vue'
 
 const props = defineProps<{
@@ -11,6 +13,8 @@ const props = defineProps<{
 
 const { page } = useData()
 
+const icon = useIcon(() => props.item.icon)
+
 const href = computed(() =>
   typeof props.item.link === 'function'
     ? props.item.link(page.value)
@@ -29,13 +33,15 @@ const { closeScreen } = inject(navInjectionKey)!
     :no-icon="item.noIcon"
     @click="closeScreen"
   >
+    <Icon v-if="icon" :icon="icon" class="shrink-0 mr-0.5" />
     <span v-html="item.text"></span>
   </VPLink>
 </template>
 
 <style scoped>
 .VPNavScreenMenuLink {
-  display: block;
+  display: flex;
+  align-items: center;
   border-bottom: 1px solid var(--vp-c-divider);
   padding: 12px 0 11px;
   line-height: 24px;

package/src/components/vitepress-default/VPSidebarItem.vue

@@ -2,6 +2,8 @@
 import type { DefaultTheme } from 'vitepress/theme'
 import { computed } from 'vue'
 import { useSidebarItemControl } from '@vp-composables/sidebar'
+import { useIcon } from '@vp-composables/icon'
+import { Icon } from '@iconify/vue'
 import VPLink from './VPLink.vue'
 
 const props = defineProps<{
@@ -52,10 +54,12 @@ function onItemInteraction(e: MouseEvent | Event) {
 function onCaretClick() {
   props.item.link && toggle()
 }
+
+const itemIcon = useIcon(() => (props.item as any).icon)
 </script>
 
 <template>
-  <component :is="sectionTag" class="VPSidebarItem" :class="classes">
+  <component :is="sectionTag" class="VPSidebarItem" :class="[classes, { 'has-icon': itemIcon }]">
     <div
       v-if="item.text"
       class="item"
@@ -77,9 +81,13 @@ function onCaretClick() {
         :rel="item.rel"
         :target="item.target"
       >
+        <Icon v-if="itemIcon" :icon="itemIcon" class="sidebar-icon shrink-0 mr-0.5" />
         <component :is="textTag" class="text" v-html="item.text" />
       </VPLink>
-      <component v-else :is="textTag" class="text" v-html="item.text" />
+      <template v-else>
+        <Icon v-if="itemIcon" :icon="itemIcon" class="sidebar-icon shrink-0 mr-0.5" />
+        <component :is="textTag" class="text" v-html="item.text" />
+      </template>
 
       <div
         v-if="item.collapsed != null && item.items && item.items.length"
@@ -112,6 +120,8 @@ function onCaretClick() {
 .item {
   position: relative;
   display: flex;
+  align-items: center;
+  gap: 6px;
   width: 100%;
 }
 
@@ -139,6 +149,7 @@ function onCaretClick() {
 .link {
   display: flex;
   align-items: center;
+  gap: 6px;
   flex-grow: 1;
 }
 
@@ -229,6 +240,7 @@ function onCaretClick() {
   transform: rotate(0)/*rtl:rotate(180deg)*/;
 }
 
+.VPSidebarItem.level-0.has-icon > .items,
 .VPSidebarItem.level-1 .items,
 .VPSidebarItem.level-2 .items,
 .VPSidebarItem.level-3 .items,
@@ -241,4 +253,22 @@ function onCaretClick() {
 .VPSidebarItem.collapsed .items {
   display: none;
 }
+
+.sidebar-icon {
+  color: var(--vp-c-brand-1);
+  height: 1.2em;
+  width: 1.2em;
+}
+
+/* Child-level icons (framework logos etc.) use text color instead of brand.
+   Multi-color icons have explicit SVG fills and are unaffected. */
+.VPSidebarItem:not(.level-0) > .item .sidebar-icon {
+  color: var(--vp-c-text-1);
+  height: 1em;
+  width: 1em;
+}
+
+.VPSidebarItem.level-0.has-icon > .items {
+  margin-left: 6px;
+}
 </style>

package/src/composables/vitepress-default/icon.ts

@@ -0,0 +1,13 @@
+import { computed, type MaybeRefOrGetter, toValue } from 'vue'
+import { useData } from './data'
+import type { IconOption } from '../../types/theme-config'
+
+export function useIcon(icon: MaybeRefOrGetter<IconOption | undefined>) {
+  const { isDark } = useData()
+  return computed(() => {
+    const val = toValue(icon)
+    if (!val) return undefined
+    if (typeof val === 'string') return val
+    return isDark.value ? val.dark : val.light
+  })
+}

package/src/index.ts

@@ -94,6 +94,7 @@ export type {
   FooterLink,
   FooterSocialLink,
   GridSize,
+  IconOption,
   Sponsor,
   SponsorTier,
   VoidZeroThemeConfig,

package/src/types/theme-config.ts

@@ -4,6 +4,11 @@
 
 import type { DefaultTheme } from 'vitepress/theme'
 
+/**
+ * Icon option — a single string for both modes, or per-mode variants
+ */
+export type IconOption = string | { light: string; dark: string }
+
 /**
  * Grid size options for sponsor display
  */
@@ -98,5 +103,18 @@ declare module 'vitepress' {
       variant?: 'voidzero' | 'viteplus' | 'vite' | 'vitest' | 'rolldown' | 'oxc'
       banner?: BannerConfig
     }
+
+    // Add icon support to nav and sidebar items
+    interface NavItemWithLink {
+      icon?: IconOption
+    }
+
+    interface NavItemWithChildren {
+      icon?: IconOption
+    }
+
+    // Note: SidebarItem is a type alias (not interface) so it can't be
+    // augmented. Sidebar icon support works via runtime casting in
+    // VPSidebarItem.vue — the icon property is passed through config objects.
   }
 }