nuxt-ai-ready 1.5.7 → 1.5.8

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": ">=4.0.0"
   },
   "configKey": "aiReady",
-  "version": "1.5.7",
+  "version": "1.5.8",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { mkdir, writeFile, appendFile, stat, access, readFile } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { useLogger, useNuxt, addTypeTemplate, addTemplate, defineNuxtModule, createResolver, hasNuxtModule, addServerPlugin, addServerHandler, addPlugin } from '@nuxt/kit';
+import { mkdir, writeFile, appendFile, stat, readdir, access, readFile } from 'node:fs/promises';
+import { join, dirname, relative, resolve } from 'node:path';
+import { useLogger, useNuxt, resolveFiles, addTypeTemplate, addTemplate, defineNuxtModule, createResolver, hasNuxtModule, addServerPlugin, addServerHandler, addPlugin } from '@nuxt/kit';
 import defu from 'defu';
 import { installNuxtSiteConfig, useSiteConfig, withSiteUrl } from 'nuxt-site-config/kit';
 import { setupDevToolsUI } from 'nuxtseo-shared/devtools';
@@ -9,7 +9,7 @@ import { resolveNuxtContentVersion } from 'nuxtseo-shared/kit';
 import { readPackageJSON, resolvePackageJSON } from 'pkg-types';
 import { parseSitemapXml } from '@nuxtjs/sitemap/utils';
 import { colorize } from 'consola/utils';
-import { withLeadingSlash, withBase } from 'ufo';
+import { withLeadingSlash, withBase, joinURL } from 'ufo';
 import { normalizePagePath, toMarkdownPath } from '../dist/runtime/markdown-path.js';
 import { toLogicalRoute, toDeployedRoute } from '../dist/runtime/route-path.js';
 import { initSchema, computeContentHash, insertPage, queryAllPages, exportDbDump } from '../dist/runtime/server/db/shared.js';
@@ -25,6 +25,41 @@ const PRERENDER_PAGE_TIMEOUT = 3e4;
 const RE_HTML_MD_EXT = /\.(html|md)$/;
 const RE_INDEX_SUFFIX = /\/index$/;
 const RE_MD_EXT = /\.md$/;
+const RE_NEGATED_GLOB = /^(!?)(.*)$/;
+const RE_PARENT_DIR_GLOB = /!?\.\.\//;
+const MARKDOWN_LINK_AVAILABILITY_FILE = "markdown-link-availability.json";
+async function findOutputMarkdownPaths(publicDir, baseURL, srcDir, ignoredPaths, publicAssets) {
+  const paths = /* @__PURE__ */ new Set();
+  async function visit(directory, urlBase, relativeDirectory = "") {
+    const entries = await readdir(directory, { withFileTypes: true });
+    await Promise.all(entries.map(async (entry) => {
+      const relativePath = join(relativeDirectory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(join(directory, entry.name), urlBase, relativePath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const urlPath = joinURL(urlBase, relativePath.replaceAll("\\", "/"));
+        paths.add(joinURL(baseURL, urlPath));
+      }
+    }));
+  }
+  await visit(publicDir, "/");
+  for (const asset of publicAssets) {
+    const patterns = [
+      "**/*.md",
+      ...ignoredPaths.map((ignoredPath) => {
+        const [, negated = "", pattern = ""] = ignoredPath.match(RE_NEGATED_GLOB) || [];
+        const assetPattern = pattern.startsWith("*") ? pattern : relative(asset.dir, resolve(srcDir, pattern)).replaceAll("\\", "/");
+        return `${negated ? "" : "!"}${assetPattern}`;
+      }).filter((pattern) => !RE_PARENT_DIR_GLOB.test(pattern))
+    ];
+    const files = await resolveFiles(asset.dir, patterns);
+    for (const file of files) {
+      const urlPath = joinURL(asset.baseURL || "/", relative(asset.dir, file).replaceAll("\\", "/"));
+      paths.add(joinURL(baseURL, urlPath));
+    }
+  }
+  return [...paths].sort();
+}
 async function fetchPreviousMeta(siteUrl, indexNow) {
   const metaUrl = withBase("/__ai-ready/pages.meta.json", siteUrl);
   logger.info(`Fetching previous build meta from ${metaUrl}`);
@@ -399,6 +434,20 @@ function setupPrerenderHandler(options, dbPath, siteInfo, llmsTxtConfig, indexNo
           await submitIndexNow(changed, added, state.siteInfo.url, state.indexNow);
         }
       }
+      if (state.dbPath && state.llmsTxtConfig?.markdownLinks) {
+        const availabilityFile = join(dirname(state.dbPath), MARKDOWN_LINK_AVAILABILITY_FILE);
+        const paths = await findOutputMarkdownPaths(
+          nitro.options.output.publicDir,
+          nitro.options.baseURL,
+          nitro.options.srcDir,
+          nitro.options.ignore,
+          nitro.options.publicAssets
+        );
+        await writeFile(availabilityFile, JSON.stringify({
+          runtimeMarkdownAvailable: !nitro.options.static,
+          paths
+        }), "utf-8");
+      }
       const llmsStats = await prerenderRoute(nitro, "/llms.txt");
       const llmsFullStats = await stat(state.llmsFullTxtPath);
       nitro._prerenderedRoutes.push({ route: "/llms-full.txt", fileName: "/llms-full.txt" });
@@ -464,6 +513,10 @@ export {}
   addTemplate({
     filename: "types/ai-ready-virtual.d.ts",
     getContents: () => `declare module '#ai-ready-virtual/read-page-data.mjs' {
+  export function readMarkdownLinkAvailabilityFromFilesystem(): Promise<{
+    runtimeMarkdownAvailable: boolean
+    paths: string[]
+  }>
   export function readPageDataFromFilesystem(): Promise<{
     pages: Array<{
       route: string
@@ -765,12 +818,13 @@ const module$1 = defineNuxtModule({
       }
     }
     const mergedLlmsTxt = config.llmsTxt ? {
+      markdownLinks: config.llmsTxt.markdownLinks ?? false,
       sections: [
         ...defaultLlmsTxtSections,
         ...config.llmsTxt.sections || []
       ],
       notes: config.llmsTxt.notes
-    } : { sections: defaultLlmsTxtSections };
+    } : { markdownLinks: false, sections: defaultLlmsTxtSections };
     const llmsTxtPayload = {
       sections: mergedLlmsTxt.sections || [],
       notes: typeof mergedLlmsTxt.notes === "string" ? [mergedLlmsTxt.notes] : mergedLlmsTxt.notes || []
@@ -859,7 +913,30 @@ const module$1 = defineNuxtModule({
         }
       }
       nitroConfig.virtual = nitroConfig.virtual || {};
-      nitroConfig.virtual["#ai-ready-virtual/read-page-data.mjs"] = nuxt.options.dev ? `export async function readPageDataFromFilesystem() { return { pages: [], errorRoutes: [] } }` : `
+      const markdownLinkAvailabilityPath = join(dirname(buildDbPath), MARKDOWN_LINK_AVAILABILITY_FILE);
+      nitroConfig.virtual["#ai-ready-virtual/read-page-data.mjs"] = nuxt.options.dev ? `
+export async function readPageDataFromFilesystem() { return { pages: [], errorRoutes: [] } }
+export async function readMarkdownLinkAvailabilityFromFilesystem() { return { runtimeMarkdownAvailable: false, paths: [] } }
+` : `
+export async function readMarkdownLinkAvailabilityFromFilesystem() {
+  if (!import.meta.prerender) {
+    return { runtimeMarkdownAvailable: false, paths: [] }
+  }
+
+  const { readFile } = await import('node:fs/promises')
+  try {
+    const availability = JSON.parse(await readFile(${JSON.stringify(markdownLinkAvailabilityPath)}, 'utf8'))
+    return {
+      runtimeMarkdownAvailable: availability?.runtimeMarkdownAvailable === true,
+      paths: Array.isArray(availability?.paths) ? availability.paths.filter(path => typeof path === 'string') : [],
+    }
+  }
+  catch (error) {
+    console.warn('[nuxt-ai-ready] Failed to read Markdown link availability; keeping canonical links.', error)
+    return { runtimeMarkdownAvailable: false, paths: [] }
+  }
+}
+
 export async function readPageDataFromFilesystem() {
   if (!import.meta.prerender) {
     return { pages: [], errorRoutes: [] }

package/dist/runtime/llms-txt-utils.js

@@ -1,13 +1,33 @@
 import { useRuntimeConfig } from "nitropack/runtime";
+import { decodePath } from "ufo";
 import { getSiteConfig } from "#site-config/server/composables/getSiteConfig";
 import { withSiteTrailingSlash, withSiteUrl } from "#site-config/server/composables/utils";
 import { formatAvailableLanguagesSection, formatLlmsTxtPageLink, normalizeLlmsTxtConfig } from "./llms-txt-format.js";
+import { toMarkdownPath } from "./markdown-path.js";
 import { normalizePersistedRoute, toDeployedRoute, toLogicalRoute } from "./route-path.js";
 import { queryPages } from "./server/db/queries.js";
 import { logger } from "./server/logger.js";
 import { resolveLocaleFromRoute } from "./server/utils/i18n.js";
 import { fetchSitemapUrls } from "./server/utils/sitemap.js";
 export { normalizeLlmsTxtConfig };
+function hasRuntimeMarkdownHandler(pathname) {
+  const lastSegment = pathname.split("/").pop() || "";
+  return !pathname.startsWith("/api") && !pathname.startsWith("/_") && !pathname.startsWith("/@") && !lastSegment.includes(".");
+}
+async function findMarkdownLinkAvailability() {
+  if (!import.meta.prerender) {
+    return {
+      runtimeMarkdownAvailable: true,
+      paths: /* @__PURE__ */ new Set()
+    };
+  }
+  const { readMarkdownLinkAvailabilityFromFilesystem } = await import("#ai-ready-virtual/read-page-data.mjs");
+  const availability = await readMarkdownLinkAvailabilityFromFilesystem();
+  return {
+    runtimeMarkdownAvailable: availability.runtimeMarkdownAvailable,
+    paths: new Set(availability.paths.map(decodePath))
+  };
+}
 function getGroupPrefix(url, depth) {
   const segments = url.split("/").filter(Boolean);
   if (segments.length === 0)
@@ -177,8 +197,20 @@ Canonical Origin: ${canonicalSiteUrl}`);
       seenPaths.add(pathname);
     }
   }
+  let resolvePageHref = resolvePath;
+  if (llmsTxtConfig.markdownLinks) {
+    const markdownLinkAvailability = await findMarkdownLinkAvailability();
+    resolvePageHref = (pathname) => {
+      const deployedPathname = resolvePath(pathname);
+      const markdownPath = resolvePath(toMarkdownPath(pathname));
+      if (markdownLinkAvailability.paths.has(decodePath(markdownPath)) || markdownLinkAvailability.runtimeMarkdownAvailable && hasRuntimeMarkdownHandler(pathname)) {
+        return markdownPath;
+      }
+      return deployedPathname;
+    };
+  }
   for (const page of [...prerendered, ...other])
-    page.href = resolvePath(page.pathname);
+    page.href = resolvePageHref(page.pathname);
   if (i18n) {
     const pageCounts = /* @__PURE__ */ new Map();
     for (const locale of i18n.locales) pageCounts.set(locale.code, 0);
@@ -186,7 +218,7 @@ Canonical Origin: ${canonicalSiteUrl}`);
       const code = p.locale || resolveLocaleFromRoute(p.pathname, i18n).locale;
       pageCounts.set(code, (pageCounts.get(code) ?? 0) + 1);
     }
-    parts.push(...formatAvailableLanguagesSection(i18n, pageCounts, resolvePath));
+    parts.push(...formatAvailableLanguagesSection(i18n, pageCounts, resolvePageHref));
     parts.push("");
   }
   const isDefaultLocale = (item) => {

package/dist/runtime/types.d.ts

@@ -271,6 +271,13 @@ export interface LlmsTxtSection {
  * Structured llms.txt configuration
  */
 export interface LlmsTxtConfig {
+    /**
+     * Rewrite automatically generated page links to their Markdown representation
+     * when the final static output contains the file or the deployment retains
+     * the runtime Markdown handler.
+     * @default false
+     */
+    markdownLinks?: boolean;
     /** The sections of the documentation */
     sections?: LlmsTxtSection[];
     /** Additional heading-free preamble notes rendered before file-list sections */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ai-ready",
   "type": "module",
-  "version": "1.5.7",
+  "version": "1.5.8",
   "description": "Best practice AI & LLM discoverability for Nuxt sites.",
   "author": {
     "name": "Harlan Wilton",