feat: version aware minimum version badge

app/components/content/VersionBadge.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { NuxtLink } from '#components'
+import type { BadgeProps } from '@nuxt/ui'
+
+interface Props extends Omit<BadgeProps, 'label'> {
+  /** A version number, or one of the {@link VERSION_KEYWORDS} like `unreleased` for something without a version yet. */
+  version: string | VersionKeyword
+  /** How far behind the latest release the requirement may be. Defaults to the whole current major. */
+  tolerance?: VersionTolerance
+  /** Overrides the release announcement or nightly guide the badge links to. */
+  to?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  color: 'info',
+  variant: 'subtle',
+  size: 'md',
+  // A page badge stays relevant for the whole major it documents
+  tolerance: () => ({ major: 0 })
+})
+
+const { show, label, ariaLabel, to } = useVersionBadge(() => props.version, { tolerance: () => props.tolerance })
+
+const link = computed(() => props.to ?? to.value)
+
+const badgeProps = computed(() => {
+  const { version, tolerance, to, ...rest } = props
+  return rest
+})
+</script>
+
+<template>
+  <UBadge
+    v-if="show"
+    v-bind="badgeProps"
+    :as="link ? NuxtLink : props.as"
+    :to="link"
+    :label="label"
+    class="align-middle"
+    :class="link && 'transition-opacity hover:opacity-75'"
+    :aria-label="ariaLabel"
+  />
+</template>

app/composables/useBlog.ts

@@ -1,5 +1,21 @@
 import type { BlogArticle } from '~/types'
 
+/**
+ * Paths of the release announcements, e.g. `/blog/v4-5`. Kept to paths only so version badges
+ * can check whether a release has a post to link to without pulling the whole blog.
+ */
+export const useReleaseArticlePaths = () => {
+  const { data: paths } = useAsyncData('release-article-paths', () => {
+    return queryCollection('blog')
+      .where('category', '=', 'Release')
+      .select('path')
+      .all()
+      .then(articles => articles.map(article => article.path))
+  }, { default: () => [] })
+
+  return { paths }
+}
+
 export const useBlog = () => {
   const { data: articles, refresh } = useAsyncData<BlogArticle[]>('blog', async () => {
     return queryCollection('blog')

app/composables/useDocsVersion.ts

@@ -1,3 +1,4 @@
+import { coerce } from 'verkit'
 import type { BadgeProps } from '@nuxt/ui'
 
 interface Version {
@@ -51,8 +52,8 @@ const tagMap: Record<Version['shortTag'], string> = {
 }
 
 export const useDocsTags = () => {
-  const { data: tags } = useAsyncData('versions', async () => {
-    const { 'dist-tags': distTags } = await $fetch<{ 'dist-tags': Record<string, string> }>('https://registry.npmjs.org/nuxt')
+  const { data: tags } = useAsyncData('versions', async (_nuxtApp, { signal }) => {
+    const { 'dist-tags': distTags } = await $fetch<{ 'dist-tags': Record<string, string> }>('https://registry.npmjs.org/nuxt', { signal })
     return Object.fromEntries(
       Object.entries(tagMap).map(([shortTag]: [keyof typeof tagMap, string]) => {
         // TODO: remove nightly fallback when Nuxt 5 is released
@@ -65,6 +66,22 @@ export const useDocsTags = () => {
   return { tags }
 }
 
+/** Latest release of the docs version being read, e.g. `4.5.2` */
+export const useDocsLatestVersion = () => {
+  const { version } = useDocsVersion()
+  const { tags } = useDocsTags()
+
+  const latest = computed(() => {
+    const shortTag = version.value?.shortTag
+    if (!shortTag) return undefined
+
+    // Falls back to the branch major (`v4` -> `4.0.0`) while the dist-tags are loading
+    return coerce(tags.value[shortTag] ?? '') ?? coerce(shortTag.slice(1)) ?? undefined
+  })
+
+  return { latest }
+}
+
 export const useDocsVersion = () => {
   const route = useRoute()
   const { track } = useAnalytics()

app/composables/useVersionBadge.ts

@@ -0,0 +1,49 @@
+import type { MaybeRefOrGetter } from 'vue'
+
+export interface UseVersionBadgeOptions {
+  /** How far behind the latest release the requirement may be. Defaults to the whole current major. */
+  tolerance?: MaybeRefOrGetter<VersionTolerance>
+}
+
+/**
+ * Decides whether a minimum Nuxt version is worth surfacing as a badge for the docs
+ * version currently being read — a requirement older than `tolerance` is not news anymore.
+ *
+ * `version` takes a version number or one of the {@link VERSION_KEYWORDS}, e.g. `unreleased`.
+ */
+export const useVersionBadge = (version: MaybeRefOrGetter<string | undefined>, options: UseVersionBadgeOptions = {}) => {
+  const { version: docsVersion } = useDocsVersion()
+  const { latest } = useDocsLatestVersion()
+
+  const labels = computed(() => versionBadgeLabels(toValue(version), docsVersion.value?.shortTag))
+  const label = computed(() => labels.value?.label)
+  /** For tight spots like the sidebar — `soon` instead of `nightly v4` */
+  const shortLabel = computed(() => labels.value?.shortLabel)
+  const ariaLabel = computed(() => labels.value?.ariaLabel)
+
+  const show = computed(() => satisfiesVersionTolerance(toValue(version), latest.value, toValue(options.tolerance) ?? { major: 0 }))
+
+  const { paths: releasePaths } = useReleaseArticlePaths()
+
+  /**
+   * Where the badge points: the nightly channel guide for a keyword, the release announcement
+   * for a version number. `undefined` while a release has no post yet, so the badge stays plain
+   * text instead of linking into a 404.
+   */
+  const to = computed(() => {
+    const value = toValue(version)
+    if (versionKeyword(value)) return nightlyChannelPath(docsVersion.value?.path)
+
+    const path = versionBlogPath(value)
+    return path && releasePaths.value.includes(path) ? path : undefined
+  })
+
+  return {
+    label,
+    shortLabel,
+    ariaLabel,
+    to,
+    show,
+    latest
+  }
+}

app/pages/docs/[...slug].vue

@@ -18,6 +18,7 @@ const onThisPageDrawerOpen = ref(false)
 const route = useRoute()
 const nuxtApp = useNuxtApp()
 const { version } = useDocsVersion()
+const { latest } = useDocsLatestVersion()
 const { headerLinks } = useHeaderLinks()
 const { isAgentDocked } = useNuxtAgent()
 const path = computed(() => route.path.replace(/\/$/, ''))
@@ -30,14 +31,42 @@ const navClass = (item: ContentNavigationItem) => {
   return ''
 }
 
+// The navigation only flags what is genuinely new: the current and previous two minors
+const navVersionTolerance: VersionTolerance = { minor: 2 }
+
+const versionBadge = (item: ContentNavigationItem) => {
+  if (typeof item.minimalVersion !== 'string') return undefined
+
+  const minimal = item.minimalVersion.trim()
+  if (!satisfiesVersionTolerance(minimal, latest.value, navVersionTolerance)) return undefined
+
+  const labels = versionBadgeLabels(minimal, version.value?.shortTag)
+  if (!labels) return undefined
+
+  return {
+    // The sidebar has no room for `nightly v4`
+    'label': labels.shortLabel,
+    'size': 'sm' as const,
+    'color': 'info' as const,
+    'variant': 'subtle' as const,
+    'aria-label': labels.ariaLabel
+  }
+}
+
+const withVersionBadge = (item: ContentNavigationItem): ContentNavigationItem => ({
+  ...item,
+  badge: versionBadge(item) ?? item.badge,
+  children: item.children?.map(withVersionBadge)
+})
+
 // Get the aside navigation
 const asideNavigation = computed(() => {
   const path = [version.value.path, route.params.slug?.[version.value.path.split('/').length - 2]].filter(Boolean).join('/')
 
   const nav = navPageFromPath(path, navigation.value)?.children || []
 
   return nav.map(item => ({
-    ...item,
+    ...withVersionBadge(item),
     class: navClass(item)
   }))
 })
@@ -219,16 +248,7 @@ const noRightAside = computed(() => route.path.includes('/examples/'))
 
           <template #title>
             {{ page.title }}
-
-            <UBadge
-              v-if="page.minimalVersion?.trim()"
-              :label="`v${page.minimalVersion?.trim()}`"
-              color="info"
-              variant="subtle"
-              size="lg"
-              class="align-middle"
-              :aria-label="`Minimum Nuxt version: v${page.minimalVersion?.trim()}`"
-            />
+            <VersionBadge v-if="page.minimalVersion?.trim()" :version="page.minimalVersion" size="lg" />
           </template>
 
           <template #links>

app/utils/version.ts

@@ -0,0 +1,108 @@
+import { coerce, getMajor, getMinor, getPatch, isGreaterOrEqual } from 'verkit'
+
+/**
+ * Shortcuts for a requirement that has no version number yet, mapped to how they render:
+ * `label` where there is room, `short` in tight spots like the sidebar.
+ * They stand for something unreleased, so tolerance never filters them out.
+ */
+export const VERSION_KEYWORDS = {
+  unreleased: { label: 'nightly', short: 'Soon' }
+} as const
+
+export type VersionKeyword = keyof typeof VERSION_KEYWORDS
+
+/** The keyword `version` stands for, if it is one. */
+export function versionKeyword(version: string | undefined | null): VersionKeyword | undefined {
+  const value = version?.trim().toLowerCase()
+  return value && value in VERSION_KEYWORDS ? value as VersionKeyword : undefined
+}
+
+/**
+ * How a minimum version requirement reads as a badge — a version number as `v<version>`,
+ * a keyword as its label qualified by the major it applies to (`unreleased` -> `nightly v4`,
+ * `soon` where space is tight). The aria label always spells out the long form.
+ * Returns `undefined` when there is nothing to show.
+ */
+export function versionBadgeLabels(version: string | undefined | null, tag?: string): { label: string, shortLabel: string, ariaLabel: string } | undefined {
+  const value = version?.trim()
+  if (!value) return undefined
+
+  const keyword = versionKeyword(value)
+  const label = keyword ? [VERSION_KEYWORDS[keyword].label, tag].filter(Boolean).join(' ') : `v${value}`
+  const shortLabel = keyword ? VERSION_KEYWORDS[keyword].short : label
+
+  return { label, shortLabel, ariaLabel: `Minimum Nuxt Version: ${label}` }
+}
+
+/**
+ * Where the release announcement for a version lives, e.g. `4.5.2` -> `/blog/v4-5`.
+ * A major release drops the minor (`4.0.0` -> `/blog/v4`), matching how the posts are named.
+ * The path is derived, not verified — check it against the blog collection before linking.
+ */
+export function versionBlogPath(version: string | undefined | null): string | undefined {
+  const target = coerce(version?.trim() ?? '')
+  if (!target) return undefined
+
+  const minor = getMinor(target)
+
+  return `/blog/v${getMajor(target)}${minor ? `-${minor}` : ''}`
+}
+
+/** The nightly release channel guide for a docs version, e.g. `/docs/4.x` -> how to install nightly. */
+export function nightlyChannelPath(docsPath: string | undefined): string | undefined {
+  if (!docsPath?.startsWith('/docs')) return undefined
+
+  return `${docsPath}/guide/going-further/nightly-release-channel`
+}
+
+/**
+ * How far *behind* the latest release a version may be and still be worth surfacing.
+ * Tolerance only ever looks backwards — versions newer than the latest release
+ * (unreleased minors, the next major) are always accepted.
+ *
+ * The finest given level sets the granularity, everything below it is zeroed:
+ * - `{ major: 0 }` keeps the whole current major
+ * - `{ major: 1 }` keeps the previous major too
+ * - `{ minor: 1 }` keeps the current and previous minor only
+ * - `{ patch: 2 }` keeps the current minor from two patches back
+ */
+export interface VersionTolerance {
+  major?: number
+  minor?: number
+  patch?: number
+}
+
+/**
+ * Lowest version still within `tolerance` of `latest`,
+ * e.g. `4.4.0` for latest `4.5.2` with `{ minor: 1 }`.
+ */
+export function versionThreshold(latest: string | undefined | null, tolerance: VersionTolerance = {}): string | undefined {
+  const release = coerce(latest ?? '')
+  if (!release) return undefined
+
+  const { major, minor, patch } = tolerance
+  const back = (value: number, offset = 0) => Math.max(0, value - offset)
+
+  return [
+    back(getMajor(release), major),
+    minor !== undefined ? back(getMinor(release), minor) : patch !== undefined ? getMinor(release) : 0,
+    patch !== undefined ? back(getPatch(release), patch) : 0
+  ].join('.')
+}
+
+/**
+ * Whether `version` is at or above the tolerated threshold, which means:
+ * - a keyword like `unreleased` -> always `true`, it describes a version that has no number yet
+ * - newer than `latest` -> always `true`
+ * - older than `latest` -> `true` while it is within `tolerance`
+ * - unparseable input -> `false`
+ */
+export function satisfiesVersionTolerance(version: string | undefined | null, latest: string | undefined | null, tolerance: VersionTolerance = {}): boolean {
+  if (versionKeyword(version)) return true
+
+  const target = coerce(version?.trim() ?? '')
+  const threshold = versionThreshold(latest, tolerance)
+  if (!target || !threshold) return false
+
+  return isGreaterOrEqual(target, threshold)
+}

package.json

@@ -80,6 +80,7 @@
     "std-env": "^4.2.0",
     "ufo": "^1.6.4",
     "valibot": "^1.4.2",
+    "verkit": "^0.3.0",
     "zod": "4.4.3"
   },
   "devDependencies": {

server/api/navigation.json.get.ts

@@ -8,9 +8,9 @@ export default defineEventHandler(async (event) => {
   // `null` entry. Every consumer iterates these items reading `item.path`, so a
   // single null took down SSR for the whole docs section.
   return Promise.all([
-    queryCollectionNavigation(event, 'docsv3', ['titleTemplate']).then(data => data[0]?.children ?? []),
-    queryCollectionNavigation(event, 'docsv4', ['titleTemplate']).then(data => data[0]?.children ?? []),
-    queryCollectionNavigation(event, 'docsv5', ['titleTemplate']).then(data => data[0]?.children ?? []),
+    queryCollectionNavigation(event, 'docsv3', ['titleTemplate', 'minimalVersion']).then(data => data[0]?.children ?? []),
+    queryCollectionNavigation(event, 'docsv4', ['titleTemplate', 'minimalVersion']).then(data => data[0]?.children ?? []),
+    queryCollectionNavigation(event, 'docsv5', ['titleTemplate', 'minimalVersion']).then(data => data[0]?.children ?? []),
     queryCollectionNavigation(event, 'blog')
   ]).then(data => data.flat().filter(Boolean))
 })