@movk/nuxt-docs 1.6.1 → 1.7.0

package/app/app.config.ts

@@ -70,5 +70,42 @@ export default defineAppConfig({
         timeZone: 'Asia/Shanghai'
       }
     }
+  },
+  aiChat: {
+    floatingInput: true,
+    explainWithAi: true,
+    shortcuts: {
+      focusInput: 'meta_i'
+    },
+    texts: {
+      title: 'AI 助手',
+      collapse: '折叠',
+      expand: '展开',
+      clearChat: '清除聊天记录',
+      close: '关闭',
+      loading: 'Loading...',
+      askAnything: '问我任何事情...',
+      askMeAnythingDescription: '我可以帮助您浏览文档、解释概念并回答您的问题。',
+      faq: 'FAQ 建议',
+      placeholder: '输入你的问题...',
+      lineBreak: '换行',
+      trigger: '与 AI 聊天',
+      streaming: '思考中...',
+      streamed: '思考过程',
+      explainWithAi: '用 AI 解释此页面'
+    },
+    icons: {
+      loading: 'i-lucide-loader',
+      trigger: 'i-lucide-sparkles',
+      explain: 'i-lucide-brain',
+      close: 'i-lucide-x',
+      clearChat: 'i-lucide-trash-2',
+      streaming: 'i-lucide-chevron-down',
+      providers: {
+        mistral: 'i-simple-icons-mistralai',
+        kwaipilot: 'i-lucide-wand',
+        zai: 'i-lucide-wand'
+      }
+    }
   }
 })

package/app/app.vue

@@ -7,6 +7,7 @@ const site = useSiteConfig()
 const appConfig = useAppConfig()
 const colorMode = useColorMode()
 const route = useRoute()
+const { isEnabled: isAiChatEnabled, panelWidth: aiChatPanelWidth, shouldPushContent } = useAIChat()
 
 const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('docs', ['category', 'description']))
 const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs'), {
@@ -48,9 +49,9 @@ provide('navigation', rootNavigation)
     <Analytics v-if="appConfig.vercelAnalytics" :debug="appConfig.vercelAnalytics?.debug" />
     <SpeedInsights v-if="appConfig.vercelAnalytics" :debug="appConfig.vercelAnalytics?.debug" />
 
-    <div :class="{ root: route.path.startsWith('/docs/') }">
+    <div :class="{ root: route.path.startsWith('/docs/') }" :style="{ marginRight: shouldPushContent ? `${aiChatPanelWidth}px` : '0' }">
       <template v-if="!route.path.startsWith('/examples')">
-        <Header />
+        <Header v-if="$route.meta.header !== false" />
       </template>
 
       <NuxtLayout>
@@ -58,10 +59,14 @@ provide('navigation', rootNavigation)
       </NuxtLayout>
 
       <template v-if="!route.path.startsWith('/examples')">
-        <Footer />
+        <Footer v-if="$route.meta.footer !== false" />
 
         <ClientOnly>
           <LazyUContentSearch :files="files" :navigation="rootNavigation" :fuse="{ resultLimit: 1000 }" />
+          <template v-if="isAiChatEnabled">
+            <LazyAiChatFloatingInput />
+            <LazyAiChatPanel />
+          </template>
         </ClientOnly>
       </template>
     </div>

package/app/components/DocsAsideRightBottom.vue

@@ -1,29 +1,24 @@
 <script setup lang="ts">
-const { aiChat } = useRuntimeConfig().public
 const route = useRoute()
-
 const pageUrl = route.path
-const { open } = useAIChat()
-const { faqQuestions } = useFaq()
+
+const { aiChat } = useAppConfig()
+const { isEnabled, open } = useAIChat()
+
+const showExplainWithAi = computed(() => {
+  return isEnabled.value && aiChat.explainWithAi !== false
+})
 </script>
 
 <template>
-  <div v-if="aiChat.enable">
-    <UButton
-      icon="i-lucide-brain"
-      target="_blank"
-      label="用 AI 解释此页面"
-      size="sm"
-      variant="ghost"
-      color="neutral"
-      @click="open(`解释此页面 ${pageUrl}`, true)"
-    />
-    <AiChatSlideover :faq-questions="faqQuestions" />
-
-    <Teleport to="body">
-      <ClientOnly>
-        <LazyAiChatFloatingInput />
-      </ClientOnly>
-    </Teleport>
-  </div>
+  <UButton
+    v-if="showExplainWithAi"
+    :icon="aiChat.icons.explain"
+    target="_blank"
+    :label="aiChat.texts.explainWithAi"
+    size="sm"
+    variant="ghost"
+    color="neutral"
+    @click="open(`解释此页面 ${pageUrl}`, true)"
+  />
 </template>

package/app/components/PageHeaderLinks.vue

@@ -106,7 +106,12 @@ async function copyPage() {
         content: 'w-48'
       }"
     >
-      <UButton :icon="ui.icons.chevronDown" color="neutral" variant="outline" />
+      <UButton
+        :icon="ui.icons.chevronDown"
+        color="neutral"
+        variant="outline"
+        aria-label="Toggle Dropdown"
+      />
     </UDropdownMenu>
   </UFieldGroup>
 </template>

package/app/components/content/PageLastCommit.vue

@@ -67,9 +67,9 @@ const authorUrl = computed(() => {
 
 <template>
   <div v-if="commit" class="flex items-center flex-wrap gap-1.5 text-sm text-muted mt-2">
-    <span class="text-dimmed">最后更新于</span>
+    <span class="text-muted">最后更新于</span>
     <time class="font-medium text-default" :datetime="commit.date">{{ commit.dateFormatted }}</time>
-    <span class="text-dimmed">由</span>
+    <span class="text-muted">由</span>
     <ULink
       v-if="authorUrl"
       :to="authorUrl"
@@ -79,7 +79,7 @@ const authorUrl = computed(() => {
       <UAvatar
         v-if="showAvatar && commit.author.avatar"
         :src="commit.author.avatar"
-        :alt="commit.author.name"
+        alt="Author Avatar"
         size="2xs"
       />
       <UBadge color="neutral" variant="outline" size="sm">
@@ -90,7 +90,7 @@ const authorUrl = computed(() => {
       <UAvatar
         v-if="showAvatar && commit.author.avatar"
         :src="commit.author.avatar"
-        :alt="commit.author.name"
+        alt="Author Avatar"
         size="2xs"
       />
       <UBadge color="neutral" variant="outline" size="sm">
@@ -98,7 +98,7 @@ const authorUrl = computed(() => {
       </UBadge>
     </span>
     <template v-if="showMessage && commit.message">
-      <span class="text-dimmed">提交</span>
+      <span class="text-muted">提交</span>
       <ULink
         v-if="commitUrl"
         :to="commitUrl"

package/app/components/header/Header.vue

@@ -18,7 +18,7 @@ const links = computed<ButtonProps[]>(() => github && github.url
 </script>
 
 <template>
-  <UHeader :ui="{ left: 'min-w-0' }" class="flex flex-col">
+  <UHeader :ui="{ left: 'min-w-0' }" class="flex flex-col" aria-label="Site Header">
     <template #left>
       <HeaderLogo />
     </template>

package/app/components/header/HeaderBody.vue

@@ -9,11 +9,21 @@ const { navigationByCategory } = useNavigation(navigation!)
 </script>
 
 <template>
-  <UNavigationMenu orientation="vertical" :items="mobileLinks" class="-mx-2.5" />
+  <UNavigationMenu
+    orientation="vertical"
+    :items="mobileLinks"
+    class="-mx-2.5"
+    aria-label="Mobile Navigation"
+  />
 
   <template v-if="route.path.startsWith('/docs/')">
     <USeparator type="dashed" class="mt-4 mb-6" />
 
-    <UContentNavigation :navigation="navigationByCategory" highlight :ui="{ linkTrailingBadge: 'font-semibold uppercase' }" />
+    <UContentNavigation
+      :navigation="navigationByCategory"
+      highlight
+      :ui="{ linkTrailingBadge: 'font-semibold uppercase' }"
+      aria-label="Documentation Navigation"
+    />
   </template>
 </template>

package/app/components/header/HeaderBottom.vue

@@ -21,6 +21,7 @@ const items = computed(() => mapContentNavigation(navigation?.value?.map(item =>
       variant="pill"
       highlight
       class="-mx-2.5 -mb-px"
+      aria-label="Category Navigation"
     />
   </UContainer>
 </template>

package/app/components/header/HeaderCTA.vue

@@ -1,10 +1,10 @@
 <script lang="ts" setup>
-const { aiChat } = useRuntimeConfig().public
 const route = useRoute()
+const { isEnabled: isAiChatEnabled } = useAIChat()
 </script>
 
 <template>
-  <div v-if="aiChat.enable" class="hidden md:block">
+  <div v-if="isAiChatEnabled" class="hidden md:block">
     <UButton
       v-if="route.path === '/'"
       to="/docs"

package/app/components/header/HeaderCenter.vue

@@ -3,5 +3,5 @@ const { desktopLinks } = useHeader()
 </script>
 
 <template>
-  <UNavigationMenu :items="desktopLinks" variant="link" />
+  <UNavigationMenu :items="desktopLinks" variant="link" aria-label="Main Navigation" />
 </template>

package/app/components/header/HeaderLogo.vue

@@ -4,6 +4,6 @@ const { header } = useAppConfig()
 
 <template>
   <NuxtLink :to="header.to">
-    <UUser :avatar="{ src: header.avatar }" :name="header.title" />
+    <UUser :avatar="{ src: header.avatar, alt: 'Site Logo' }" :name="header.title" />
   </NuxtLink>
 </template>

package/app/layouts/default.vue

@@ -1,3 +1,5 @@
 <template>
-  <slot />
+  <UMain>
+    <slot />
+  </UMain>
 </template>

package/app/layouts/docs.vue

@@ -1,5 +1,5 @@
 <template>
-  <UMain class="relative">
+  <UMain class="relative" as="main">
     <HeroBackground />
 
     <UContainer>

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

@@ -17,6 +17,7 @@ if (!page.value) {
 }
 
 const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
+const { shouldPushContent: shouldHideToc } = useAIChat()
 
 const { data: surround } = await useAsyncData(`surround-${(kebabCase(route.path))}`, () => {
   return queryCollectionItemSurroundings('docs', route.path, {
@@ -93,7 +94,7 @@ defineOgImageComponent('Nuxt', {
 </script>
 
 <template>
-  <UPage v-if="page">
+  <UPage v-if="page" :key="`page-${shouldHideToc}`">
     <UPageHeader :title="title">
       <template #headline>
         <UBreadcrumb :items="breadcrumb" />
@@ -136,7 +137,7 @@ defineOgImageComponent('Nuxt', {
       <UContentSurround :surround="surround" />
     </UPageBody>
 
-    <template v-if="page?.body?.toc?.links?.length" #right>
+    <template v-if="page?.body?.toc?.links?.length && !shouldHideToc" #right>
       <UContentToc
         :title="toc?.title"
         :links="page.body?.toc?.links"

package/app/templates/releases.vue

@@ -0,0 +1,98 @@
+<script setup lang="ts">
+import type { ButtonProps } from '@nuxt/ui'
+
+const { data: page } = await useAsyncData('releases', () => queryCollection('releases').first())
+if (!page.value) {
+  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+}
+
+const title = page.value.seo?.title || page.value.title
+const description = page.value.seo?.description || page.value.description
+
+useSeoMeta({
+  title,
+  description,
+  ogTitle: title,
+  ogDescription: description
+})
+
+defineOgImageComponent('Nuxt', {
+  title,
+  description
+})
+
+const { data: versions } = await useFetch(page.value.releases || '', {
+  server: false,
+  transform: (data: {
+    releases: {
+      name?: string
+      tag: string
+      publishedAt: string
+      markdown: string
+    }[]
+  }) => {
+    return data.releases.map(release => ({
+      tag: release.tag,
+      title: release.name || release.tag,
+      date: release.publishedAt,
+      markdown: release.markdown
+    }))
+  }
+})
+</script>
+
+<template>
+  <main v-if="page">
+    <UPageHero
+      :title="page.hero.title"
+      :description="page.hero.description"
+      :links="(page.hero.links as ButtonProps[]) || []"
+      class="md:border-b border-default"
+      :ui="{ container: 'relative py-10 sm:py-16 lg:py-24' }"
+    >
+      <template #top>
+        <div class="absolute z-[-1] rounded-full bg-primary blur-[300px] size-60 sm:size-80 transform -translate-x-1/2 left-1/2 -translate-y-80" />
+      </template>
+
+      <LazyStarsBg />
+
+      <div aria-hidden="true" class="hidden md:block absolute z-[-1] border-x border-default inset-0 mx-4 sm:mx-6 lg:mx-8" />
+    </UPageHero>
+
+    <UPageSection :ui="{ container: 'py-0!' }">
+      <div class="py-4 md:py-8 lg:py-16 md:border-x border-default">
+        <UContainer class="max-w-5xl">
+          <UChangelogVersions
+            as="main"
+            :indicator-motion="false"
+            :ui="{
+              root: 'py-16 sm:py-24 lg:py-32',
+              indicator: 'inset-y-0'
+            }"
+          >
+            <UChangelogVersion
+              v-for="version in versions"
+              :key="version.tag"
+              v-bind="version"
+              :ui="{
+                root: 'flex items-start',
+                container: 'max-w-xl',
+                header: 'border-b border-default pb-4',
+                title: 'text-3xl',
+                date: 'text-xs/9 text-highlighted font-mono',
+                indicator: 'sticky top-0 pt-16 -mt-16 sm:pt-24 sm:-mt-24 lg:pt-32 lg:-mt-32'
+              }"
+            >
+              <template #body>
+                <MDC
+                  v-if="version.markdown"
+                  :value="version.markdown"
+                />
+              </template>
+            </UChangelogVersion>
+          </UChangelogVersions>
+        </UContainer>
+      </div>
+    </UPageSection>
+  </main>
+</template>

package/app/types/index.d.ts

@@ -61,6 +61,155 @@ declare module 'nuxt/schema' {
         options?: Intl.DateTimeFormatOptions
       }
     } | false
+    aiChat: {
+      /**
+       * 在文档页面底部显示浮动输入。
+       * @default true
+       */
+      floatingInput: boolean
+      /**
+       * 在文档侧边栏中显示“使用 AI 进行解释”按钮。
+       * @default true
+       */
+      explainWithAi?: boolean
+      /**
+       * 显示的常见问题解答问题。
+       * @example 简单格式: ['如何安装？', '如何配置？']
+       * @example 分类格式: [{ category: '入门', items: ['如何安装？'] }]
+       */
+      faqQuestions?: FaqQuestions
+      /**
+       * 键盘快捷键配置。
+       */
+      shortcuts: {
+        /**
+         * 快捷键，用于聚焦浮动输入框。
+         * @default 'meta_i'
+         */
+        focusInput: string
+      }
+      /**
+       * 文本配置。
+       */
+      texts: {
+        /**
+         * AI 聊天面板的标题文本。
+         * @default 'AI 助手'
+         */
+        title: string
+        /**
+         * 折叠按钮的文本。
+         * @default '折叠‘
+         */
+        collapse: string
+        /**
+         * 展开按钮的文本。
+         * @default '展开'
+         */
+        expand: string
+        /**
+         * 清除聊天记录按钮的文本。
+         * @default '清除聊天记录'
+         */
+        clearChat: string
+        /**
+         * 关闭按钮的文本。
+         * @default '关闭'
+         */
+        close: string
+        /**
+         * 加载时的提示文本。
+         * @default 'Loading...'
+         */
+        loading: string
+        /**
+         * 询问任何事情文本
+         * @default '问我任何事情...'
+         */
+        askAnything: string
+        /**
+         * 询问任何事情描述文本
+         * @default '我可以帮助您浏览文档、解释概念并回答您的问题。'
+         */
+        askMeAnythingDescription: string
+        /**
+         * FAQ 建议标题文本。
+         * @default 'FAQ 建议'
+         */
+        faq: string
+        /**
+         * 浮动输入框的占位符文本。
+         * @default '输入你的问题...'
+         */
+        placeholder: string
+        /**
+         * 换行的提示文本。
+         * @default '换行'
+         */
+        lineBreak: string
+        /**
+         * AI 聊天面板触发按钮的提示文本。
+         * @default '与 AI 聊天'
+         */
+        trigger: string
+        /**
+         * 思考时的提示文本。
+         * @default '思考中...'
+         */
+        streaming: string
+        /**
+         * 思考后的提示文本。
+         * @default '思考过程'
+         */
+        streamed: string
+        /**
+         * 使用 AI 进行解释按钮的文本。
+         * @default '用 AI 解释此页面
+         */
+        explainWithAi: string
+      }
+      /**
+       * 图标配置。
+       */
+      icons: {
+        /**
+         * 加载时的图标。
+         * @default i-lucide-loader
+         */
+        loading: string
+        /**
+         * AI 聊天触发按钮和滑出层头部的图标。
+         * @default 'i-lucide-sparkles'
+         */
+        trigger: string
+        /**
+         * "使用 AI 进行解释" 按钮的图标。
+         * @default 'i-lucide-brain'
+         */
+        explain: string
+        /**
+         * 思考时的图标。
+         * @default ui.icons.chevronDown
+         */
+        streaming: string
+        /**
+         * 清除聊天记录按钮的图标。
+         * @default 'i-lucide-trash-2'
+         */
+        clearChat: string
+        /**
+         * 关闭按钮的图标。
+         * @default 'i-lucide-x'
+         */
+        close: string
+        /**
+         * 用于映射不同 AI 提供商的图标。
+         * @example { mistral: 'i-simple-icons-mistralai' }
+         * @default { xxx: 'i-simple-xxx', mistral: 'i-simple-icons-mistralai', kwaipilot: 'i-lucide-wand', zai: 'i-lucide-wand' }
+         */
+        providers: Record<string, string>
+      }
+    }
   }
 }
 

package/content.config.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs'
 import { defineCollection, defineContentConfig } from '@nuxt/content'
 import { useNuxt } from '@nuxt/kit'
 import { asSeoCollection } from '@nuxtjs/seo/content'
@@ -7,6 +8,8 @@ import { z } from 'zod/v4'
 const { options } = useNuxt()
 const cwd = joinURL(options.rootDir, 'content')
 
+const hasReleasesMd = existsSync(joinURL(cwd, 'releases.md'))
+
 const Avatar = z.object({
   src: z.string(),
   alt: z.string().optional()
@@ -27,6 +30,12 @@ const Button = z.object({
   class: z.string().optional()
 })
 
+const PageHero = z.object({
+  title: z.string(),
+  description: z.string(),
+  links: z.array(Button).optional()
+})
+
 export default defineContentConfig({
   collections: {
     landing: defineCollection(asSeoCollection({
@@ -38,10 +47,10 @@ export default defineContentConfig({
     })),
     docs: defineCollection(asSeoCollection({
       type: 'page',
-      source: [{
+      source: {
         cwd,
         include: 'docs/**/*'
-      }],
+      },
       schema: z.object({
         links: z.array(Button),
         category: z.string().optional(),
@@ -49,6 +58,19 @@ export default defineContentConfig({
           title: z.string().optional()
         })
       })
+    })),
+    releases: defineCollection(asSeoCollection({
+      type: 'page',
+      source: {
+        cwd,
+        include: hasReleasesMd ? 'releases.md' : 'releases.yml'
+      },
+      schema: z.object({
+        title: z.string(),
+        description: z.string(),
+        releases: z.string(),
+        hero: PageHero
+      })
     }))
   }
 })