docus 5.4.4 → 5.5.1

package/app/app.vue

@@ -5,6 +5,7 @@ import * as nuxtUiLocales from '@nuxt/ui/locale'
 const { seo } = useAppConfig()
 const site = useSiteConfig()
 const { locale, locales, isEnabled, switchLocalePath } = useDocusI18n()
+const { isEnabled: isAssistantEnabled, panelWidth: assistantPanelWidth, shouldPushContent } = useAssistant()
 
 const nuxtUiLocale = computed(() => nuxtUiLocales[locale.value as keyof typeof nuxtUiLocales] || nuxtUiLocales.en)
 const lang = computed(() => nuxtUiLocale.value.code)
@@ -47,7 +48,7 @@ const { data: navigation } = await useAsyncData(() => `navigation_${collectionNa
   transform: (data: ContentNavigationItem[]) => {
     const rootResult = data.find(item => item.path === '/docs')?.children || data || []
 
-    return rootResult.find(item => item.path === `/${locale.value}`)?.children || rootResult
+    return rootResult.find((item: ContentNavigationItem) => item.path === `/${locale.value}`)?.children || rootResult
   },
   watch: [locale],
 })
@@ -63,17 +64,26 @@ provide('navigation', navigation)
   <UApp :locale="nuxtUiLocale">
     <NuxtLoadingIndicator color="var(--ui-primary)" />
 
-    <AppHeader v-if="$route.meta.header !== false" />
-    <NuxtLayout>
-      <NuxtPage />
-    </NuxtLayout>
-    <AppFooter v-if="$route.meta.footer !== false" />
+    <div
+      class="transition-[margin-right] duration-200 ease-linear will-change-[margin-right]"
+      :style="{ marginRight: shouldPushContent ? `${assistantPanelWidth}px` : '0' }"
+    >
+      <AppHeader v-if="$route.meta.header !== false" />
+      <NuxtLayout>
+        <NuxtPage />
+      </NuxtLayout>
+      <AppFooter v-if="$route.meta.footer !== false" />
+    </div>
 
     <ClientOnly>
       <LazyUContentSearch
         :files="files"
         :navigation="navigation"
       />
+      <template v-if="isAssistantEnabled">
+        <LazyAssistantPanel />
+        <LazyAssistantFloatingInput />
+      </template>
     </ClientOnly>
   </UApp>
 </template>

package/app/components/app/AppHeader.vue

@@ -4,6 +4,7 @@ import { useDocusI18n } from '../../composables/useDocusI18n'
 const appConfig = useAppConfig()
 const site = useSiteConfig()
 
+const { isEnabled: isAssistantEnabled } = useAssistant()
 const { localePath, isEnabled, locales } = useDocusI18n()
 
 const links = computed(() => appConfig.github && appConfig.github.url
@@ -33,6 +34,10 @@ const links = computed(() => appConfig.github && appConfig.github.url
     <template #right>
       <AppHeaderCTA />
 
+      <template v-if="isAssistantEnabled">
+        <AssistantChat />
+      </template>
+
       <template v-if="isEnabled && locales.length > 1">
         <ClientOnly>
           <LanguageSelect />

package/app/components/docs/DocsAsideRightBottom.vue

@@ -1,18 +1,45 @@
 <script setup lang="ts">
+const route = useRoute()
+
+const pageUrl = route.path
 const appConfig = useAppConfig()
 const { t } = useDocusI18n()
+const { isEnabled, open } = useAssistant()
+
+const showExplainWithAi = computed(() => {
+  return isEnabled.value && appConfig.assistant?.explainWithAi !== false
+})
+
+const explainIcon = computed(() => appConfig.assistant?.icons?.explain || 'i-lucide-brain')
 </script>
 
 <template>
   <div
-    v-if="appConfig.toc?.bottom?.links?.length"
+    v-if="appConfig.toc?.bottom?.links?.length || showExplainWithAi"
     class="hidden lg:block space-y-6"
   >
     <USeparator type="dashed" />
 
     <UPageLinks
+      v-if="appConfig.toc?.bottom?.links?.length"
       :title="appConfig.toc?.bottom?.title || t('docs.links')"
       :links="appConfig.toc?.bottom?.links"
     />
+
+    <USeparator
+      v-if="appConfig.toc?.bottom?.links?.length && showExplainWithAi"
+      type="dashed"
+    />
+
+    <UButton
+      v-if="showExplainWithAi"
+      :icon="explainIcon"
+      :label="t('assistant.explainWithAi')"
+      size="sm"
+      variant="link"
+      class="p-0 text-sm"
+      color="neutral"
+      @click="open(`Explain the page ${pageUrl}`, true)"
+    />
   </div>
 </template>

package/app/composables/useSeo.ts

@@ -0,0 +1,207 @@
+import type { MaybeRefOrGetter } from 'vue'
+import type { BreadcrumbItem } from '../utils/navigation'
+import { joinURL, withoutTrailingSlash } from 'ufo'
+
+export interface UseSeoOptions {
+  /**
+   * Page title
+   */
+  title: MaybeRefOrGetter<string | undefined>
+  /**
+   * Page description
+   */
+  description: MaybeRefOrGetter<string | undefined>
+  /**
+   * Page type for og:type (default: 'article' for docs, 'website' for landing)
+   */
+  type?: MaybeRefOrGetter<'website' | 'article'>
+  /**
+   * Custom OG image URL (absolute)
+   */
+  ogImage?: MaybeRefOrGetter<string | undefined>
+  /**
+   * Published date for article schema
+   */
+  publishedAt?: MaybeRefOrGetter<string | undefined>
+  /**
+   * Modified date for article schema
+   */
+  modifiedAt?: MaybeRefOrGetter<string | undefined>
+  /**
+   * Breadcrumb items for BreadcrumbList schema
+   */
+  breadcrumbs?: MaybeRefOrGetter<BreadcrumbItem[] | undefined>
+}
+
+/**
+ * Composable for comprehensive SEO setup including:
+ * - Meta tags (title, description, og:*, twitter:*)
+ * - Canonical URLs
+ * - Hreflang tags for i18n
+ * - JSON-LD structured data
+ */
+export function useSeo(options: UseSeoOptions) {
+  const route = useRoute()
+  const site = useSiteConfig()
+  const { locale, locales, isEnabled: isI18nEnabled, switchLocalePath } = useDocusI18n()
+
+  const title = computed(() => toValue(options.title))
+  const description = computed(() => toValue(options.description))
+  const type = computed(() => toValue(options.type) || 'article')
+  const ogImage = computed(() => toValue(options.ogImage))
+  const publishedAt = computed(() => toValue(options.publishedAt))
+  const modifiedAt = computed(() => toValue(options.modifiedAt))
+  const breadcrumbs = computed(() => toValue(options.breadcrumbs))
+
+  // Build canonical URL
+  const canonicalUrl = computed(() => {
+    if (!site.url) return undefined
+    return joinURL(site.url, route.path)
+  })
+
+  // Base URL for building other URLs
+  const baseUrl = computed(() => site.url ? withoutTrailingSlash(site.url) : '')
+
+  // Set meta tags
+  useSeoMeta({
+    title,
+    description,
+    ogTitle: title,
+    ogDescription: description,
+    ogType: type,
+    ogUrl: canonicalUrl,
+    ogLocale: computed(() => isI18nEnabled.value ? locale.value : undefined),
+  })
+
+  // Set canonical link
+  useHead({
+    link: computed(() => {
+      const links: Array<{ rel: string, href?: string, hreflang?: string }> = []
+
+      // Canonical URL
+      if (canonicalUrl.value) {
+        links.push({
+          rel: 'canonical',
+          href: canonicalUrl.value,
+        })
+      }
+
+      // Hreflang tags for i18n
+      if (isI18nEnabled.value && baseUrl.value) {
+        for (const loc of locales) {
+          const localePath = switchLocalePath(loc.code)
+          if (localePath) {
+            links.push({
+              rel: 'alternate',
+              hreflang: loc.code,
+              href: joinURL(baseUrl.value, localePath),
+            })
+          }
+        }
+
+        // x-default hreflang (points to default locale)
+        const defaultLocalePath = switchLocalePath(locales[0]?.code || 'en')
+        if (defaultLocalePath) {
+          links.push({
+            rel: 'alternate',
+            hreflang: 'x-default',
+            href: joinURL(baseUrl.value, defaultLocalePath),
+          })
+        }
+      }
+
+      return links
+    }),
+  })
+
+  // Custom OG image handling
+  if (ogImage.value) {
+    useSeoMeta({
+      ogImage: ogImage.value,
+      twitterImage: ogImage.value,
+    })
+  }
+
+  // JSON-LD structured data
+  useHead({
+    script: computed(() => {
+      const scripts: Array<{ type: string, innerHTML: string }> = []
+
+      if (!baseUrl.value || !title.value) return scripts
+
+      const pageUrl = joinURL(baseUrl.value, route.path)
+
+      // Article schema for documentation pages
+      if (type.value === 'article') {
+        const articleSchema: Record<string, unknown> = {
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          'headline': title.value,
+          'description': description.value,
+          'url': pageUrl,
+          'mainEntityOfPage': {
+            '@type': 'WebPage',
+            '@id': pageUrl,
+          },
+        }
+
+        if (publishedAt.value) {
+          articleSchema.datePublished = publishedAt.value
+        }
+
+        if (modifiedAt.value) {
+          articleSchema.dateModified = modifiedAt.value
+        }
+
+        if (site.name) {
+          articleSchema.publisher = {
+            '@type': 'Organization',
+            'name': site.name,
+          }
+        }
+
+        scripts.push({
+          type: 'application/ld+json',
+          innerHTML: JSON.stringify(articleSchema),
+        })
+      }
+
+      // WebSite schema for landing pages
+      if (type.value === 'website') {
+        const websiteSchema: Record<string, unknown> = {
+          '@context': 'https://schema.org',
+          '@type': 'WebSite',
+          'name': site.name || title.value,
+          'description': description.value,
+          'url': baseUrl.value,
+        }
+
+        scripts.push({
+          type: 'application/ld+json',
+          innerHTML: JSON.stringify(websiteSchema),
+        })
+      }
+
+      // BreadcrumbList schema for navigation
+      if (breadcrumbs.value && breadcrumbs.value.length > 0) {
+        const breadcrumbSchema = {
+          '@context': 'https://schema.org',
+          '@type': 'BreadcrumbList',
+          'itemListElement': breadcrumbs.value.map((item, index) => ({
+            '@type': 'ListItem',
+            'position': index + 1,
+            'name': item.title,
+            'item': joinURL(baseUrl.value, item.path),
+          })),
+        }
+
+        scripts.push({
+          type: 'application/ld+json',
+          innerHTML: JSON.stringify(breadcrumbSchema),
+        })
+      }
+
+      return scripts
+    }),
+  })
+}

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

@@ -11,6 +11,7 @@ const route = useRoute()
 const { locale, isEnabled, t } = useDocusI18n()
 const appConfig = useAppConfig()
 const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
+const { shouldPushContent: shouldHideToc } = useAssistant()
 
 const collectionName = computed(() => isEnabled.value ? `docs_${locale.value}` : 'docs')
 
@@ -30,14 +31,16 @@ if (!page.value) {
 const title = page.value.seo?.title || page.value.title
 const description = page.value.seo?.description || page.value.description
 
-useSeoMeta({
+const headline = ref(findPageHeadline(navigation?.value, page.value?.path))
+const breadcrumbs = computed(() => findPageBreadcrumbs(navigation?.value, page.value?.path || ''))
+
+useSeo({
   title,
-  ogTitle: title,
   description,
-  ogDescription: description,
+  type: 'article',
+  modifiedAt: (page.value as unknown as Record<string, unknown>).modifiedAt as string | undefined,
+  breadcrumbs,
 })
-
-const headline = ref(findPageHeadline(navigation?.value, page.value?.path))
 watch(() => navigation?.value, () => {
   headline.value = findPageHeadline(navigation?.value, page.value?.path) || headline.value
 })
@@ -62,10 +65,16 @@ const editLink = computed(() => {
     `${page.value?.stem}.${page.value?.extension}`,
   ].filter(Boolean).join('/')
 })
+
+// Add the page path to the prerender list
+addPrerenderPath(`/raw${route.path}.md`)
 </script>
 
 <template>
-  <UPage v-if="page">
+  <UPage
+    v-if="page"
+    :key="`page-${shouldHideToc}`"
+  >
     <UPageHeader
       :title="page.title"
       :description="page.description"
@@ -92,9 +101,8 @@ const editLink = computed(() => {
         :value="page"
       />
 
-      <USeparator>
+      <USeparator v-if="github">
         <div
-          v-if="github"
           class="flex items-center gap-2 text-sm text-muted"
         >
           <UButton
@@ -124,7 +132,7 @@ const editLink = computed(() => {
     </UPageBody>
 
     <template
-      v-if="page?.body?.toc?.links?.length"
+      v-if="page?.body?.toc?.links?.length && !shouldHideToc"
       #right
     >
       <UContentToc

package/app/plugins/i18n.ts

@@ -1,5 +1,10 @@
-import en from '../../i18n/locales/en.json'
 import type { RouteLocationNormalized } from 'vue-router'
+import { consola } from 'consola'
+
+const log = consola.withTag('Docus')
+
+// Lazy import functions for locale files (bundled but not eagerly loaded)
+const localeFiles = import.meta.glob<{ default: Record<string, unknown> }>('../../i18n/locales/*.json')
 
 export default defineNuxtPlugin(async () => {
   const nuxtApp = useNuxtApp()
@@ -8,19 +13,31 @@ export default defineNuxtPlugin(async () => {
 
   // If i18n is not enabled, fetch and provide the configured locale in app config
   if (!i18nConfig) {
-    let locale = 'en'
-    let resolvedMessages: Record<string, unknown> = en
-
     const appConfig = useAppConfig()
-    const configuredLocale = appConfig.docus.locale
-    if (configuredLocale !== 'en') {
-      const localeMessages = await import(`../../i18n/locales/${configuredLocale}.json`)
-      if (!localeMessages) {
-        console.warn(`[Docus] Missing locale file for "${configuredLocale}". Falling back to "en".`)
+    const configuredLocale = appConfig.docus.locale || 'en'
+
+    let locale = configuredLocale
+    let resolvedMessages: Record<string, unknown>
+
+    // Try to load the requested locale file
+    const localeKey = `../../i18n/locales/${configuredLocale}.json`
+    const localeLoader = localeFiles[localeKey]
+
+    if (localeLoader) {
+      const localeModule = await localeLoader()
+      resolvedMessages = localeModule.default
+    }
+    else {
+      log.warn(`Missing locale file for "${configuredLocale}". Falling back to "en".`)
+      locale = 'en'
+      const fallbackKey = '../../i18n/locales/en.json'
+      const fallbackLoader = localeFiles[fallbackKey]
+      if (fallbackLoader) {
+        const fallbackModule = await fallbackLoader()
+        resolvedMessages = fallbackModule.default
       }
       else {
-        locale = configuredLocale
-        resolvedMessages = localeMessages
+        resolvedMessages = {} as Record<string, unknown>
       }
     }
 

package/app/templates/landing.vue

@@ -15,20 +15,14 @@ if (!page.value) {
 const title = page.value.seo?.title || page.value.title
 const description = page.value.seo?.description || page.value.description
 
-useSeoMeta({
+useSeo({
   title,
   description,
-  ogTitle: title,
-  ogDescription: description,
+  type: 'website',
+  ogImage: page.value?.seo?.ogImage as string | undefined,
 })
 
-if (page.value?.seo?.ogImage) {
-  useSeoMeta({
-    ogImage: page.value.seo.ogImage,
-    twitterImage: page.value.seo.ogImage,
-  })
-}
-else {
+if (!page.value?.seo?.ogImage) {
   defineOgImageComponent('Landing', {
     title,
     description,

package/app/types/index.d.ts

@@ -1,3 +1,7 @@
+import type { FaqQuestions, LocalizedFaqQuestions } from '../../modules/assistant/runtime/types'
+
+export type { FaqCategory, FaqQuestions, LocalizedFaqQuestions } from '../../modules/assistant/runtime/types'
+
 declare module 'nuxt/schema' {
   interface AppConfig {
     docus: {
@@ -36,6 +40,51 @@ declare module 'nuxt/schema' {
       branch: string
       rootDir?: string
     } | false
+    assistant?: {
+      /**
+       * Show the floating input at the bottom of documentation pages.
+       * @default true
+       */
+      floatingInput?: boolean
+      /**
+       * Show the "Explain with AI" button in the documentation sidebar.
+       * @default true
+       */
+      explainWithAi?: boolean
+      /**
+       * FAQ questions to display in the chat slideover.
+       * Can be a simple array of strings, an array of categories, or a locale-based object.
+       * @example Simple format: ['How to install?', 'How to configure?']
+       * @example Category format: [{ category: 'Getting Started', items: ['How to install?'] }]
+       * @example Localized format: { en: ['How to install?'], fr: ['Comment installer ?'] }
+       */
+      faqQuestions?: FaqQuestions | LocalizedFaqQuestions
+      /**
+       * Keyboard shortcuts configuration.
+       */
+      shortcuts?: {
+        /**
+         * Shortcut to focus the floating input.
+         * @default 'meta_i'
+         */
+        focusInput?: string
+      }
+      /**
+       * Icons configuration.
+       */
+      icons?: {
+        /**
+         * Icon for the assistant trigger button and slideover header.
+         * @default 'i-lucide-sparkles'
+         */
+        trigger?: string
+        /**
+         * Icon for the "Explain with AI" button.
+         * @default 'i-lucide-brain'
+         */
+        explain?: string
+      }
+    }
   }
 }
 

package/app/utils/navigation.ts

@@ -5,3 +5,34 @@ export const flattenNavigation = (items?: ContentNavigationItem[]): ContentNavig
     ? flattenNavigation(item.children)
     : [item],
 ) || []
+
+export interface BreadcrumbItem {
+  title: string
+  path: string
+}
+
+/**
+ * Find breadcrumb path to a page in the navigation tree
+ */
+export function findPageBreadcrumbs(
+  navigation: ContentNavigationItem[] | undefined,
+  path: string,
+  currentPath: BreadcrumbItem[] = [],
+): BreadcrumbItem[] | undefined {
+  if (!navigation) return undefined
+
+  for (const item of navigation) {
+    const itemPath = [...currentPath, { title: item.title, path: item.path }]
+
+    if (item.path === path) {
+      return itemPath
+    }
+
+    if (item.children) {
+      const found = findPageBreadcrumbs(item.children, path, itemPath)
+      if (found) return found
+    }
+  }
+
+  return undefined
+}

package/i18n/locales/en.json

@@ -18,5 +18,32 @@
     "toc": "On this page",
     "report": "Report an issue",
     "edit": "Edit this page"
+  },
+  "assistant": {
+    "title": "Ask AI",
+    "placeholder": "Ask a question...",
+    "tooltip": "Ask AI a question",
+    "tryAsking": "Try asking a question",
+    "askAnything": "Ask anything...",
+    "clearChat": "Clear chat",
+    "close": "Close",
+    "expand": "Expand",
+    "collapse": "Collapse",
+    "thinking": "Thinking...",
+    "askMeAnything": "Ask anything",
+    "askMeAnythingDescription": "Get help navigating the documentation, understanding concepts, and finding answers.",
+    "faq": "FAQ",
+    "chatCleared": "Chat is cleared on refresh",
+    "lineBreak": "Line break",
+    "explainWithAi": "Explain with AI",
+    "toolListPages": "Listed documentation pages",
+    "toolReadPage": "Read",
+    "loading": {
+      "searching": "Searching the documentation",
+      "reading": "Reading through the docs",
+      "analyzing": "Analyzing the content",
+      "finding": "Finding the best answer",
+      "finished": "Sources used"
+    }
   }
 }

package/i18n/locales/fr.json

@@ -18,5 +18,32 @@
     "toc": "Sur cette page",
     "report": "Signaler un problème",
     "edit": "Éditer cette page"
+  },
+  "assistant": {
+    "title": "Demander à l'IA",
+    "placeholder": "Posez une question...",
+    "tooltip": "Poser une question à l'IA",
+    "tryAsking": "Essayez de poser une question",
+    "askAnything": "Demandez n'importe quoi...",
+    "clearChat": "Effacer le chat",
+    "close": "Fermer",
+    "expand": "Agrandir",
+    "collapse": "Réduire",
+    "thinking": "Réflexion...",
+    "askMeAnything": "Posez une question",
+    "askMeAnythingDescription": "Obtenez de l'aide pour naviguer dans la documentation, comprendre des concepts et trouver des réponses.",
+    "faq": "FAQ",
+    "chatCleared": "Le chat est effacé au rechargement",
+    "lineBreak": "Retour à la ligne",
+    "explainWithAi": "Expliquer avec l'IA",
+    "toolListPages": "Pages de documentation listées",
+    "toolReadPage": "Lecture de",
+    "loading": {
+      "searching": "Recherche dans la documentation",
+      "reading": "Lecture des documents",
+      "analyzing": "Analyse du contenu",
+      "finding": "Recherche de la meilleure réponse",
+      "finished": "Sources utilisées"
+    }
   }
-} 
+}