feat(docs): AI-friendly docs — markdown twins, llms.txt, copy page, upgraded search (#739)

binaryk · web-flow · commit e4b6d9701e6e · 2026-07-07T14:55:31.000+03:00
- Emit a raw-markdown twin for every docs page at &lt;url&gt;.md at build time
- Generate /docs/llms.txt, /docs/llms-full.txt and root /llms.txt indexes
- Add Forge-style Copy page split button (copy markdown, view as
  markdown, open in ChatGPT/Claude) on all docs pages
- Tune docs search: fuzzy section-level full-text via Fuse options,
  AI hint in the search modal footer
- Serve .md and llms files with markdown content types via _headers;
  wildcard-exclude /docs/* in Cloudflare Pages _routes.json to stay
  under the 100-rule limit
diff --git a/docs-v3/app.config.ts b/docs-v3/app.config.ts
@@ -1,5 +1,16 @@
 export default defineAppConfig({
     ui: {
+        // Docs search palette: highlighted match state + consistent grouped/footer styling.
+        // `<mark>` tags are injected by @nuxt/ui's fuse highlighter (includeMatches) into
+        // the heading (itemLabelBase) and body-content (itemLabelSuffix) of each result.
+        commandPalette: {
+            slots: {
+                label: 'text-xs font-semibold uppercase tracking-wide text-gray-400 dark:text-gray-500',
+                itemLabelBase: '[&_mark]:bg-blue-100 [&_mark]:dark:bg-blue-500/25 [&_mark]:text-blue-700 [&_mark]:dark:text-blue-300 [&_mark]:rounded [&_mark]:px-0.5 [&_mark]:font-semibold',
+                itemLabelSuffix: '[&_mark]:bg-blue-100/70 [&_mark]:dark:bg-blue-500/20 [&_mark]:text-blue-700 [&_mark]:dark:text-blue-300 [&_mark]:rounded [&_mark]:px-0.5',
+                footer: 'px-3 py-2.5 border-t border-gray-200 dark:border-gray-800'
+            }
+        },
         accordion: {
             slots: {
                 item: 'border-b border-gray-200 dark:border-gray-700/50 last:border-b-0',
diff --git a/docs-v3/app.vue b/docs-v3/app.vue
@@ -7,9 +7,32 @@
         shortcut="meta_k"
         :files="files"
         :navigation="navigation"
-        :fuse="{ resultLimit: 42 }"
-        placeholder="Search documentation..."
-      />
+        :fuse="searchFuse"
+        placeholder="Search the docs, headings and content…"
+      >
+        <template #footer>
+          <div class="flex flex-wrap items-center justify-between gap-x-4 gap-y-1 w-full text-xs text-gray-500 dark:text-gray-400">
+            <span class="flex items-center gap-1.5">
+              <UIcon name="i-lucide-sparkles" class="size-3.5 text-blue-500 dark:text-blue-400 shrink-0" />
+              <span>
+                <span class="font-medium text-gray-700 dark:text-gray-300">AI tip:</span>
+                append
+                <code class="px-1 py-0.5 rounded bg-gray-100 dark:bg-gray-800 font-mono text-[0.7rem] text-gray-700 dark:text-gray-300">.md</code>
+                to any docs URL for raw markdown
+              </span>
+            </span>
+            <NuxtLink
+              to="/docs/llms.txt"
+              external
+              target="_blank"
+              class="flex items-center gap-1 font-medium text-blue-500 hover:text-blue-600 dark:text-blue-400 dark:hover:text-blue-300"
+            >
+              <UIcon name="i-lucide-file-text" class="size-3.5 shrink-0" />
+              /docs/llms.txt
+            </NuxtLink>
+          </div>
+        </template>
+      </LazyUContentSearch>
     </ClientOnly>
   </UApp>
 </template>
@@ -43,4 +66,17 @@ const { data: navigation } = await useAsyncData('navigation', () => queryCollect
 const { data: files } = await useAsyncData('search', () => queryCollectionSearchSections('content'))
 
 const searchTerm = ref('')
+
+// Fuse.js tuning for AI/agent-era docs search: fuzzy, section-aware, generous recall.
+// Keys stay at the CommandPalette default (['label', 'suffix'] = heading + body content) —
+// defu concatenates arrays, so redefining them here would duplicate the defaults.
+const searchFuse = {
+  resultLimit: 20,
+  fuseOptions: {
+    ignoreLocation: true,
+    threshold: 0.3,
+    minMatchCharLength: 2,
+    includeScore: true
+  }
+}
 </script>
diff --git a/docs-v3/components/TheHeader.vue b/docs-v3/components/TheHeader.vue
@@ -21,9 +21,11 @@
 
         <div class="flex items-center space-x-4">
           <div class="hidden lg:block">
-            <UContentSearchButton 
+            <UContentSearchButton
               :collapsed="false"
-              placeholder="Search documentation..."
+              :kbds="['meta', 'K']"
+              label="Search documentation…"
+              class="w-64 justify-start text-gray-500 dark:text-gray-400"
             />
           </div>
           
@@ -58,9 +60,11 @@
     
     <div class="lg:hidden px-4 pb-4 bg-white dark:bg-gray-900 border-t border-gray-200 dark:border-gray-700 w-full">
       <div class="pt-4 w-full">
-        <UContentSearchButton 
-          :collapsed="false" 
-          placeholder="Search documentation..."
+        <UContentSearchButton
+          :collapsed="false"
+          :kbds="[]"
+          label="Search documentation…"
+          class="w-full justify-start text-gray-500 dark:text-gray-400"
         />
       </div>
     </div>
diff --git a/docs-v3/components/docs/CopyPageDropdown.vue b/docs-v3/components/docs/CopyPageDropdown.vue
@@ -0,0 +1,124 @@
+<template>
+  <div
+    class="inline-flex items-stretch rounded-lg border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900 shadow-sm overflow-hidden"
+  >
+    <button
+      type="button"
+      class="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500"
+      :aria-label="copied ? 'Copied' : 'Copy page as Markdown'"
+      @click="copyPage"
+    >
+      <UIcon
+        :name="copied ? 'i-lucide-check' : 'i-lucide-copy'"
+        class="w-4 h-4 shrink-0"
+        :class="copied ? 'text-green-600 dark:text-green-400' : ''"
+      />
+      <span>{{ copied ? 'Copied' : 'Copy page' }}</span>
+    </button>
+
+    <UDropdownMenu
+      :items="items"
+      :content="{ align: 'end', side: 'bottom', sideOffset: 6 }"
+      :ui="{ content: 'w-72' }"
+    >
+      <button
+        type="button"
+        class="inline-flex items-center px-2 border-l border-gray-200 dark:border-gray-700 text-gray-500 dark:text-gray-400 hover:bg-gray-50 dark:hover:bg-gray-800 hover:text-gray-700 dark:hover:text-gray-200 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500"
+        aria-label="More copy options"
+      >
+        <UIcon name="i-lucide-chevron-down" class="w-4 h-4" />
+      </button>
+
+      <template #item-label="{ item }">
+        <div class="flex flex-col text-left">
+          <span class="text-sm font-medium text-gray-900 dark:text-white">{{ item.label }}</span>
+          <span v-if="item.description" class="text-xs text-gray-500 dark:text-gray-400">
+            {{ item.description }}
+          </span>
+        </div>
+      </template>
+    </UDropdownMenu>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const route = useRoute()
+const config = useRuntimeConfig()
+const { copied, copyToClipboard } = useClipboardCopy()
+
+const siteUrl = config.public.siteUrl as string
+
+const mdPath = computed(() => `${route.path.replace(/\/$/, '')}.md`)
+const absoluteMdUrl = computed(() => `${siteUrl}${mdPath.value}`)
+
+const llmPrompt = computed(
+  () => `Read from ${absoluteMdUrl.value} so I can ask questions about it.`
+)
+
+const chatGptUrl = computed(
+  () => `https://chatgpt.com/?hints=search&q=${encodeURIComponent(llmPrompt.value)}`
+)
+
+const claudeUrl = computed(
+  () => `https://claude.ai/new?q=${encodeURIComponent(llmPrompt.value)}`
+)
+
+async function fetchMarkdown(): Promise<string> {
+  try {
+    const response = await fetch(mdPath.value)
+
+    if (response.ok) {
+      const text = await response.text()
+
+      if (text && !text.trimStart().startsWith('<')) {
+        return text
+      }
+    }
+  } catch {
+    // Fall through to URL fallback (e.g. .md twin missing in dev)
+  }
+
+  return absoluteMdUrl.value
+}
+
+async function copyPage(): Promise<void> {
+  const markdown = await fetchMarkdown()
+  await copyToClipboard(markdown)
+}
+
+const items = computed(() => [
+  [
+    {
+      label: 'Copy page',
+      description: 'Copy page as Markdown for LLMs',
+      icon: 'i-lucide-file-text',
+      onSelect: copyPage
+    },
+    {
+      label: 'View as Markdown',
+      description: 'Open the raw Markdown in a new tab',
+      icon: 'i-lucide-file-code',
+      to: mdPath.value,
+      target: '_blank'
+    }
+  ],
+  [
+    {
+      label: 'Open in ChatGPT',
+      description: 'Ask ChatGPT about this page',
+      icon: 'i-lucide-bot',
+      to: chatGptUrl.value,
+      target: '_blank'
+    },
+    {
+      label: 'Open in Claude',
+      description: 'Ask Claude about this page',
+      icon: 'i-lucide-sparkles',
+      to: claudeUrl.value,
+      target: '_blank'
+    }
+  ]
+])
+</script>
diff --git a/docs-v3/nuxt.config.ts b/docs-v3/nuxt.config.ts
@@ -1,3 +1,5 @@
+import { fileURLToPath } from 'node:url'
+
 const docsRoutes = [
   '/',
   '/docs',
@@ -135,6 +137,20 @@ export default defineNuxtConfig({
   // Cloudflare Pages does not understand, and exact-match rules would additionally be
   // prerendered as meta-refresh stub HTML that shadows the redirect with a 200.
 
+  // Emit Forge-style raw markdown twins and llms.txt indexes into the static
+  // output at build time. Runs after Nitro has staged public assets, so the files
+  // land in the final publicDir (dist/) alongside the prerendered pages.
+  hooks: {
+    async 'nitro:build:public-assets'(nitro) {
+      const { generateLlms } = await import('./scripts/generate-llms.mjs')
+      await generateLlms({
+        contentDir: fileURLToPath(new URL('./content/docs', import.meta.url)),
+        outputDir: nitro.options.output.publicDir,
+        siteUrl: 'https://laravel-restify.com'
+      })
+    }
+  },
+
   // TypeScript configuration
   typescript: {
     typeCheck: false
@@ -144,6 +160,22 @@ export default defineNuxtConfig({
   ssr: true,
   nitro: {
     preset: 'cloudflare_pages',
+    // Collapse the per-file static excludes into a handful of wildcards so the
+    // generated dist/_routes.json stays well under Cloudflare Pages' hard limit
+    // of 100 rules. Nitro seeds `exclude` from this config first, converts each
+    // trailing `/*` into a `/**` glob to skip matching files during its own
+    // asset walk, then appends the remaining root assets. Without this, every
+    // prerendered /docs page plus its raw `.md` twin and the llms.txt indexes
+    // were emitted as individual excludes, pinning the file at exactly 100 rules
+    // (one content page away from a rejected deploy). `/docs/*` covers all docs
+    // HTML pages, their `.md` twins, and /docs/llms{,-full}.txt in one rule.
+    cloudflare: {
+      pages: {
+        routes: {
+          exclude: ['/docs/*', '/docs.md', '/llms.txt']
+        }
+      }
+    },
     prerender: {
       failOnError: false,
       crawlLinks: true,
diff --git a/docs-v3/pages/[...slug].vue b/docs-v3/pages/[...slug].vue
@@ -2,6 +2,10 @@
   <NuxtLayout>
     <div v-if="post">
       <article>
+        <div v-if="isDocsPage" class="flex justify-end mb-4">
+          <CopyPageDropdown />
+        </div>
+
         <header class="mb-8">
           <h1 class="text-4xl font-bold text-gray-900 dark:text-white mb-4">
             {{ post.title }}
@@ -42,6 +46,8 @@ const route = useRoute()
 const pathSegments = Array.isArray(route.params.slug) ? route.params.slug : [route.params.slug || '']
 const contentPath = `/${pathSegments.join('/')}`
 
+const isDocsPage = computed(() => contentPath === '/docs' || contentPath.startsWith('/docs/'))
+
 const { data: post } = await useAsyncData(`content-${contentPath}`, function fetchContent() {
   return queryCollection('content').path(contentPath).first()
 })
diff --git a/docs-v3/public/_headers b/docs-v3/public/_headers
@@ -8,3 +8,21 @@
   cache-control: public, max-age=31536000, immutable
 /_nuxt/*
   cache-control: public, max-age=31536000, immutable
+
+# Serve the Forge-style raw markdown twins and llms.txt indexes as UTF-8 markdown
+# so AI agents and browsers render them as text rather than downloading them.
+/docs/*.md
+  content-type: text/markdown; charset=utf-8
+  cache-control: public, max-age=3600
+/docs.md
+  content-type: text/markdown; charset=utf-8
+  cache-control: public, max-age=3600
+/llms.txt
+  content-type: text/plain; charset=utf-8
+  cache-control: public, max-age=3600
+/docs/llms.txt
+  content-type: text/plain; charset=utf-8
+  cache-control: public, max-age=3600
+/docs/llms-full.txt
+  content-type: text/plain; charset=utf-8
+  cache-control: public, max-age=3600
diff --git a/docs-v3/scripts/generate-llms.mjs b/docs-v3/scripts/generate-llms.mjs
