nuxt-ai-ready 1.5.5 → 1.5.7

package/dist/module.json

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

package/dist/module.mjs

@@ -9,8 +9,9 @@ import { resolveNuxtContentVersion } from 'nuxtseo-shared/kit';
 import { readPackageJSON, resolvePackageJSON } from 'pkg-types';
 import { parseSitemapXml } from '@nuxtjs/sitemap/utils';
 import { colorize } from 'consola/utils';
-import { withBase } from 'ufo';
+import { withLeadingSlash, withBase } 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';
 import { comparePageHashes, submitToIndexNowShared } from '../dist/runtime/server/utils/indexnow-shared.js';
 import { buildLlmsFullTxtHeader, formatPageForLlmsFullTxt } from '../dist/runtime/server/utils/llms-full.js';
@@ -25,7 +26,7 @@ const RE_HTML_MD_EXT = /\.(html|md)$/;
 const RE_INDEX_SUFFIX = /\/index$/;
 const RE_MD_EXT = /\.md$/;
 async function fetchPreviousMeta(siteUrl, indexNow) {
-  const metaUrl = `${siteUrl}/__ai-ready/pages.meta.json`;
+  const metaUrl = withBase("/__ai-ready/pages.meta.json", siteUrl);
   logger.info(`Fetching previous build meta from ${metaUrl}`);
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), BUILD_FETCH_TIMEOUT);
@@ -41,7 +42,7 @@ async function fetchPreviousMeta(siteUrl, indexNow) {
   }
   logger.info(`Previous build: ${prevMeta.pageCount} pages (buildId: ${prevMeta.buildId})`);
   if (indexNow) {
-    const keyUrl = `${siteUrl}/${indexNow}.txt`;
+    const keyUrl = withBase(`/${indexNow}.txt`, siteUrl);
     const keyLive = await fetch(keyUrl, { signal: AbortSignal.timeout(5e3) }).then((r) => r.ok).catch(() => false);
     if (!keyLive) {
       logger.info("IndexNow key file not live yet - IndexNow submission will be skipped");
@@ -161,7 +162,7 @@ async function processMarkdownRoute(state, nuxt, route, parsed, lastmod, options
 async function processSitemapEntry(state, nuxt, nitro, entry) {
   const loc = typeof entry === "string" ? entry : entry.loc;
   const lastmod = typeof entry === "string" ? void 0 : entry.lastmod;
-  const route = normalizePagePath(loc.startsWith("http") ? new URL(loc).pathname : loc);
+  const route = toLogicalRoute(loc, nitro.options.baseURL);
   if (route.split("/").some((segment) => segment.startsWith("_"))) {
     return { crawled: false, skipped: true };
   }
@@ -169,7 +170,7 @@ async function processSitemapEntry(state, nuxt, nitro, entry) {
     return { crawled: false, skipped: true };
   }
   const mdRoute = toMarkdownPath(route);
-  const mdUrl = withBase(mdRoute, nitro.options.baseURL);
+  const mdUrl = toDeployedRoute(mdRoute, nitro.options.baseURL);
   logger.debug(`Fetching markdown for ${route} \u2192 ${mdUrl}`);
   const res = await globalThis.$fetch(mdUrl, {
     headers: { "x-nitro-prerender": mdRoute },
@@ -292,7 +293,8 @@ function setupPrerenderHandler(options, dbPath, siteInfo, llmsTxtConfig, indexNo
     let initPromise = null;
     nitro.hooks.hook("prerender:generate", async (route) => {
       if (route.error) {
-        const pageRoute2 = route.route.replace(RE_HTML_MD_EXT, "").replace(RE_INDEX_SUFFIX, "") || "/";
+        const routePath = route.fileName || route.route;
+        const pageRoute2 = withLeadingSlash(routePath).replace(RE_HTML_MD_EXT, "").replace(RE_INDEX_SUFFIX, "").replace(RE_HTML_MD_EXT, "") || "/";
         state.errorRoutes.add(pageRoute2);
         logger.debug(`Detected error page: ${pageRoute2}`);
         return;
@@ -614,7 +616,7 @@ const module$1 = defineNuxtModule({
       version: ">=6.0.0"
     },
     "@nuxtjs/sitemap": {
-      version: ">=8.0.0"
+      version: ">=8.3.0"
     },
     "nuxt-site-config": {
       version: ">=3.2"
@@ -727,7 +729,7 @@ const module$1 = defineNuxtModule({
     }
     registerTypeTemplates();
     const defaultLlmsTxtSections = [];
-    const llmsFullRoute = withSiteUrl("llms-full.txt");
+    const llmsFullRoute = withSiteUrl("llms-full.txt", { withBase: true });
     defaultLlmsTxtSections.push({
       title: "LLM Resources",
       links: [
@@ -750,7 +752,7 @@ const module$1 = defineNuxtModule({
       });
       const mcpLink = {
         title: "MCP",
-        href: withSiteUrl(nuxt.options.mcp !== false && nuxt.options.mcp?.route || "/mcp"),
+        href: withSiteUrl(nuxt.options.mcp !== false && nuxt.options.mcp?.route || "/mcp", { withBase: true }),
         description: "Model Context Protocol server endpoint for AI agent integration."
       };
       if (defaultLlmsTxtSections[0]) {
@@ -1038,7 +1040,7 @@ export async function lookupContentPage(event, path) {
       const siteConfig = useSiteConfig();
       setupPrerenderHandler(config, buildDbPath, {
         name: siteConfig.name,
-        url: siteConfig.url,
+        url: siteConfig.url ? withSiteUrl("/", { withBase: true }) : void 0,
         description: siteConfig.description
       }, mergedLlmsTxt, indexNow, { ftsTokenizer, i18n: i18nConfig });
     }

package/dist/runtime/llms-txt-format.d.ts

@@ -1,8 +1,19 @@
 /**
  * Pure formatting functions for llms.txt - no runtime dependencies
  */
+import type { RuntimeI18nConfig } from './server/utils/i18n.js';
 import type { LlmsTxtConfig } from './types.js';
+export declare function formatAvailableLanguagesSection(i18n: RuntimeI18nConfig, pageCounts: Map<string, number>, resolveHref?: (pathname: string) => string): string[];
+interface LlmsTxtPageLink {
+    pathname: string;
+    href?: string;
+    title?: string;
+    description?: string;
+}
+export declare function formatLlmsTxtPageLink(page: LlmsTxtPageLink): string;
 /**
- * Normalize llms.txt structured configuration to markdown string
+ * Normalize llms.txt structured configuration to the llmstxt.org Markdown format.
+ * Preamble prose must appear before the first H2; every H2 body is a file list.
  */
 export declare function normalizeLlmsTxtConfig(config: LlmsTxtConfig): string;
+export {};

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

@@ -1,39 +1,100 @@
-function normalizeLink(link) {
-  const parts = [];
-  parts.push(`- [${link.title}](${link.href})`);
-  if (link.description)
-    parts.push(`  ${link.description}`);
-  return parts.join("\n");
+import { localePath } from "./server/utils/i18n.js";
+const RE_INLINE_WHITESPACE = /\s+/g;
+const RE_LINK_TITLE_BRACKET = /[[\]]/g;
+const RE_LINK_HREF_UNSAFE = /[\s()]/g;
+const RE_PREAMBLE_ATX_HEADING = /^( {0,3})(#{1,6})(?=\s)/gm;
+function normalizeInlineText(value) {
+  return value.trim().replace(RE_INLINE_WHITESPACE, " ");
 }
-function normalizeSection(section, headingLevel = 2) {
-  const prefix = "#".repeat(headingLevel);
-  const parts = [];
-  parts.push(`${prefix} ${section.title}`);
-  parts.push("");
-  if (section.description) {
-    const descriptions = Array.isArray(section.description) ? section.description : [section.description];
-    parts.push(...descriptions);
-    parts.push("");
-  }
+function normalizeLinkTitle(value) {
+  return normalizeInlineText(value).replace(RE_LINK_TITLE_BRACKET, (bracket) => bracket === "[" ? "[" : "]");
+}
+function normalizeLinkHref(value) {
+  return value.trim().replace(RE_LINK_HREF_UNSAFE, (character) => {
+    if (character === "(")
+      return "%28";
+    if (character === ")")
+      return "%29";
+    return encodeURIComponent(character);
+  });
+}
+function normalizeDescriptions(value) {
+  return (Array.isArray(value) ? value : value ? [value] : []).filter((description) => description.trim()).map(normalizeInlineText);
+}
+function normalizePreambleBlocks(value) {
+  return (Array.isArray(value) ? value : value ? [value] : []).filter((block) => block.trim()).map((block) => block.trim().replace(RE_PREAMBLE_ATX_HEADING, "$1\\$2"));
+}
+function normalizeLink(link, descriptionPrefixes = []) {
+  const descriptions = [...descriptionPrefixes, link.description].filter((value) => Boolean(value?.trim())).map(normalizeInlineText);
+  const description = descriptions.join("; ");
+  return `- [${normalizeLinkTitle(link.title)}](${normalizeLinkHref(link.href)})${description ? `: ${description}` : ""}`;
+}
+function normalizeSection(section) {
+  const parts = [`## ${normalizeInlineText(section.title)}`];
   if (section.links?.length)
-    parts.push(...section.links.map(normalizeLink));
+    parts.push("", ...section.links.map((link) => normalizeLink(link)));
   return parts.join("\n");
 }
-export function normalizeLlmsTxtConfig(config) {
+function normalizePreamble(config) {
   const parts = [];
-  const required = config.sections?.filter((s) => !s.optional) ?? [];
-  const optional = config.sections?.filter((s) => s.optional) ?? [];
-  if (required.length)
-    parts.push(...required.map((s) => normalizeSection(s)));
-  if (optional.length) {
-    parts.push("## Optional");
-    parts.push(...optional.map((s) => normalizeSection(s, 3)));
-  }
   if (config.notes) {
-    parts.push("## Notes");
-    parts.push("");
-    const notes = Array.isArray(config.notes) ? config.notes : [config.notes];
-    parts.push(...notes);
+    const notes = normalizePreambleBlocks(config.notes);
+    if (notes.length)
+      parts.push(["**Notes:**", ...notes].join("\n\n"));
+  }
+  for (const section of config.sections?.filter((section2) => !section2.optional) ?? []) {
+    if (!section.description)
+      continue;
+    const descriptions = normalizePreambleBlocks(section.description);
+    if (descriptions.length)
+      parts.push([`**${normalizeInlineText(section.title)}:**`, ...descriptions].join("\n\n"));
   }
+  return parts;
+}
+function normalizeOptionalSections(sections) {
+  const links = sections.flatMap(
+    (section) => section.links?.map((link) => normalizeLink(link, [section.title, ...normalizeDescriptions(section.description)])) ?? []
+  );
+  if (!links.length)
+    return void 0;
+  return ["## Optional", "", ...links].join("\n");
+}
+function normalizeRequiredSections(sections) {
+  return sections.filter((section) => section.links?.length).map(normalizeSection);
+}
+export function formatAvailableLanguagesSection(i18n, pageCounts, resolveHref = (pathname) => pathname) {
+  const lines = ["## Available Languages on Website", ""];
+  for (const locale of i18n.locales) {
+    const isDefault = locale.code === i18n.defaultLocale;
+    const prefix = localePath("/", locale.code, i18n);
+    const count = pageCounts.get(locale.code) ?? 0;
+    const display = locale.nativeName ? `${locale.nativeName} (${locale.code})` : locale.name ? `${locale.name} (${locale.code})` : locale.code;
+    const suffix = isDefault ? "content included below" : "visit this language for content";
+    lines.push(normalizeLink({
+      title: display,
+      href: resolveHref(prefix),
+      description: `${count} pages; ${suffix}.`
+    }));
+  }
+  return lines;
+}
+export function formatLlmsTxtPageLink(page) {
+  const description = page.description?.trim().replace(RE_INLINE_WHITESPACE, " ");
+  const normalizedTitle = page.title ? normalizeInlineText(page.title) : "";
+  const title = normalizedTitle && normalizedTitle !== page.pathname ? normalizedTitle : page.pathname;
+  const href = (page.href || page.pathname).trim();
+  const truncatedDescription = description ? `${description.substring(0, 160)}${description.length > 160 ? "..." : ""}` : void 0;
+  return normalizeLink({ title, href, description: truncatedDescription });
+}
+export function normalizeLlmsTxtConfig(config) {
+  const required = config.sections?.filter((section) => !section.optional) ?? [];
+  const optional = config.sections?.filter((section) => section.optional) ?? [];
+  const parts = [
+    ...normalizePreamble(config),
+    ...normalizeRequiredSections(required)
+  ];
+  const optionalSection = normalizeOptionalSections(optional);
+  if (optionalSection)
+    parts.push(optionalSection);
   return parts.join("\n\n");
 }

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

@@ -1,23 +1,13 @@
 import { useRuntimeConfig } from "nitropack/runtime";
 import { getSiteConfig } from "#site-config/server/composables/getSiteConfig";
-import { normalizeLlmsTxtConfig } from "./llms-txt-format.js";
+import { withSiteTrailingSlash, withSiteUrl } from "#site-config/server/composables/utils";
+import { formatAvailableLanguagesSection, formatLlmsTxtPageLink, normalizeLlmsTxtConfig } from "./llms-txt-format.js";
+import { normalizePersistedRoute, toDeployedRoute, toLogicalRoute } from "./route-path.js";
 import { queryPages } from "./server/db/queries.js";
 import { logger } from "./server/logger.js";
-import { localePath, resolveLocaleFromRoute } from "./server/utils/i18n.js";
+import { resolveLocaleFromRoute } from "./server/utils/i18n.js";
 import { fetchSitemapUrls } from "./server/utils/sitemap.js";
 export { normalizeLlmsTxtConfig };
-function formatAvailableLanguagesSection(i18n, pageCounts) {
-  const lines = ["## Available Languages on Website", ""];
-  for (const locale of i18n.locales) {
-    const isDefault = locale.code === i18n.defaultLocale;
-    const prefix = localePath("/", locale.code, i18n);
-    const count = pageCounts.get(locale.code) ?? 0;
-    const display = locale.nativeName ? `${locale.nativeName} (${locale.code})` : locale.name ? `${locale.name} (${locale.code})` : locale.code;
-    const suffix = isDefault ? "Content included below" : "Visit website for content";
-    lines.push(`- ${display} - ${count} pages - ${prefix} - ${suffix}`);
-  }
-  return lines;
-}
 function getGroupPrefix(url, depth) {
   const segments = url.split("/").filter(Boolean);
   if (segments.length === 0)
@@ -101,11 +91,7 @@ function formatPagesWithGroups(pages) {
       urlsInCurrentGroup = 0;
     }
     urlsInCurrentGroup++;
-    const descText = page.description ? `: ${page.description.substring(0, 160)}${page.description.length > 160 ? "..." : ""}` : "";
-    if (page.title && page.title !== page.pathname)
-      lines.push(`- [${page.title}](${page.pathname})${descText}`);
-    else
-      lines.push(`- ${page.pathname}${descText}`);
+    lines.push(formatLlmsTxtPageLink(page));
   }
   return lines;
 }
@@ -116,26 +102,39 @@ export async function buildLlmsTxt(event) {
   const siteConfig = getSiteConfig(event);
   const llmsTxtConfig = aiReadyConfig.llmsTxt;
   const i18n = aiReadyConfig.i18n;
+  const baseURL = runtimeConfig.app.baseURL;
+  const resolvePath = (path) => withSiteTrailingSlash(event, toDeployedRoute(path, baseURL));
+  const resolveUrl = (path) => withSiteUrl(event, toDeployedRoute(path, baseURL));
+  const canonicalSiteUrl = siteConfig.url ? resolveUrl("/") : void 0;
   const parts = [];
-  parts.push(`# ${siteConfig.name || siteConfig.url}`);
+  parts.push(`# ${siteConfig.name || canonicalSiteUrl}`);
   if (siteConfig.description) {
     parts.push(`
 > ${siteConfig.description}`);
   }
-  if (siteConfig.url) {
+  if (canonicalSiteUrl) {
     parts.push(`
-Canonical Origin: ${siteConfig.url}`);
+Canonical Origin: ${canonicalSiteUrl}`);
   }
   parts.push("");
-  const sections = llmsTxtConfig.sections ? [...llmsTxtConfig.sections] : [];
+  const sections = llmsTxtConfig.sections?.map((section) => ({
+    ...section,
+    links: section.links ? [...section.links] : void 0
+  })) ?? [];
   if (sections[0]?.links) {
-    if (sitemapConfig?.sitemaps) {
-      const sitemapRoutes = Object.values(sitemapConfig.sitemaps).map((s) => s.sitemapName);
-      for (const name of sitemapRoutes) {
-        sections[0].links.push({ title: name, href: `/${name}`, description: "XML sitemap for search engines and crawlers." });
-      }
+    const sitemapRoutes = sitemapConfig?.sitemaps ? Object.values(sitemapConfig.sitemaps).map((s) => s.sitemapName) : ["sitemap.xml"];
+    for (const name of sitemapRoutes) {
+      sections[0].links.push({
+        title: name,
+        href: resolveUrl(`/${name}`),
+        description: "XML sitemap for search engines and crawlers."
+      });
     }
-    sections[0].links.push({ title: "robots.txt", href: "/robots.txt", description: "Crawler rules and permissions." });
+    sections[0].links.push({
+      title: "robots.txt",
+      href: resolveUrl("/robots.txt"),
+      description: "Crawler rules and permissions."
+    });
   }
   const normalizedContent = normalizeLlmsTxtConfig({ ...llmsTxtConfig, sections });
   if (normalizedContent) {
@@ -157,23 +156,29 @@ Canonical Origin: ${siteConfig.url}`);
     );
   }
   const urls = await urlsPromise;
+  const sitemapPaths = urls.map((url) => toLogicalRoute(url.loc, baseURL));
+  const sitemapPathSet = new Set(sitemapPaths);
   const seenPaths = /* @__PURE__ */ new Set();
-  const errorSet = new Set(errorPages.map((p) => p.route));
+  const errorSet = new Set(errorPages.map((p) => normalizePersistedRoute(p.route, sitemapPathSet, baseURL)));
   const prerendered = [];
   for (const page of pages) {
-    seenPaths.add(page.route);
-    prerendered.push({ pathname: page.route, title: page.title, description: page.description, locale: page.locale });
+    const pathname = normalizePersistedRoute(page.route, sitemapPathSet, baseURL);
+    if (seenPaths.has(pathname))
+      continue;
+    seenPaths.add(pathname);
+    prerendered.push({ pathname, title: page.title, description: page.description, locale: page.locale });
   }
   const devModeHint = import.meta.dev && prerendered.length === 0 ? " (dev mode - run `nuxi generate` for page titles)" : "";
   const other = [];
-  for (const url of urls) {
-    const pathname = url.loc.startsWith("/") ? url.loc : new URL(url.loc).pathname;
+  for (const pathname of sitemapPaths) {
     if (!seenPaths.has(pathname) && !errorSet.has(pathname)) {
       const locale = i18n ? resolveLocaleFromRoute(pathname, i18n).locale : void 0;
       other.push({ pathname, locale });
       seenPaths.add(pathname);
     }
   }
+  for (const page of [...prerendered, ...other])
+    page.href = resolvePath(page.pathname);
   if (i18n) {
     const pageCounts = /* @__PURE__ */ new Map();
     for (const locale of i18n.locales) pageCounts.set(locale.code, 0);
@@ -181,7 +186,7 @@ Canonical Origin: ${siteConfig.url}`);
       const code = p.locale || resolveLocaleFromRoute(p.pathname, i18n).locale;
       pageCounts.set(code, (pageCounts.get(code) ?? 0) + 1);
     }
-    parts.push(...formatAvailableLanguagesSection(i18n, pageCounts));
+    parts.push(...formatAvailableLanguagesSection(i18n, pageCounts, resolvePath));
     parts.push("");
   }
   const isDefaultLocale = (item) => {

package/dist/runtime/route-path.d.ts

@@ -0,0 +1,10 @@
+/** Convert a sitemap URL (which includes app.baseURL) to a logical route. */
+export declare function toLogicalRoute(pathOrUrl: string, baseURL: string): string;
+/** Apply app.baseURL to a logical route exactly once. */
+export declare function toDeployedRoute(route: string, baseURL: string): string;
+/**
+ * Normalize rows written by older releases, which stored deployed paths.
+ * A sitemap match disambiguates those rows from real logical routes whose
+ * first segment happens to match app.baseURL.
+ */
+export declare function normalizePersistedRoute(route: string, sitemapRoutes: ReadonlySet<string>, baseURL: string): string;

package/dist/runtime/route-path.js

@@ -0,0 +1,16 @@
+import { joinURL, parseURL, withLeadingSlash, withoutBase } from "ufo";
+import { normalizePagePath } from "./markdown-path.js";
+export function toLogicalRoute(pathOrUrl, baseURL) {
+  const pathname = withLeadingSlash(parseURL(pathOrUrl).pathname);
+  return normalizePagePath(withoutBase(pathname, baseURL));
+}
+export function toDeployedRoute(route, baseURL) {
+  return joinURL(baseURL, withLeadingSlash(route));
+}
+export function normalizePersistedRoute(route, sitemapRoutes, baseURL) {
+  const normalizedRoute = normalizePagePath(withLeadingSlash(parseURL(route).pathname));
+  if (sitemapRoutes.has(normalizedRoute))
+    return normalizedRoute;
+  const logicalRoute = toLogicalRoute(normalizedRoute, baseURL);
+  return sitemapRoutes.has(logicalRoute) ? logicalRoute : normalizedRoute;
+}

package/dist/runtime/server/db/queries.js

@@ -57,17 +57,17 @@ async function getPrerenderDb() {
       const excludeErrors = sql.includes("is_error = 0");
       const includeMarkdown = wantsMarkdown(sql);
       if (isErrorQuery) {
-        return pages.filter((p) => errorRoutes.has(p.route)).map((p) => ({
-          route: p.route,
-          title: p.title,
-          description: p.description,
-          ...includeMarkdown ? { markdown: p.markdown } : {},
-          headings: p.headings,
-          keywords: JSON.stringify(p.keywords),
-          updated_at: p.updatedAt,
+        return [...errorRoutes].map((route) => ({
+          route,
+          title: "",
+          description: "",
+          ...includeMarkdown ? { markdown: "" } : {},
+          headings: "[]",
+          keywords: "[]",
+          updated_at: "",
           is_error: 1,
           indexed: 0,
-          locale: p.locale || ""
+          locale: ""
         }));
       }
       const filtered = excludeErrors ? pages.filter((p) => !errorRoutes.has(p.route)) : pages;

package/dist/runtime/server/middleware/markdown.js

@@ -1,6 +1,7 @@
 import { createError, defineEventHandler, getHeader, sendRedirect, setHeader } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
 import { withSiteUrl } from "#site-config/server/composables/utils";
+import { toDeployedRoute } from "../../route-path.js";
 import { queryPages } from "../db/queries.js";
 import { logger } from "../logger.js";
 import { convertHtmlToMarkdown, extractLastUpdated, getMarkdownRenderInfo, toMarkdownPath } from "../utils.js";
@@ -23,7 +24,7 @@ function setMarkdownHeaders(event, path, config, resolveUrl) {
     setHeader(event, "cache-control", cacheControl);
   }
 }
-function notFoundMarkdown(canonicalUrl, path, config) {
+function notFoundMarkdown(canonicalUrl, path, config, resolveUrl) {
   const body = [
     `# Page not found`,
     ``,
@@ -31,14 +32,14 @@ function notFoundMarkdown(canonicalUrl, path, config) {
     ``,
     `Try one of these resources:`,
     ``,
-    `- [Sitemap](/sitemap.xml)`,
-    `- [llms.txt](/llms.txt)`,
-    `- [llms-full.txt](/llms-full.txt)`,
+    `- [Sitemap](${resolveUrl("/sitemap.xml")})`,
+    `- [llms.txt](${resolveUrl("/llms.txt")})`,
+    `- [llms-full.txt](${resolveUrl("/llms-full.txt")})`,
     ``
   ].join("\n");
   const i18n = config.i18n;
   const locale = i18n ? resolveLocaleFromRoute(path, i18n).locale : void 0;
-  const alternates = i18n ? computeLocaleAlternates(path, i18n).map((a) => ({ hreflang: a.hreflang, href: a.path })) : void 0;
+  const alternates = i18n ? computeLocaleAlternates(path, i18n).map((a) => ({ hreflang: a.hreflang, href: resolveUrl(a.path) })) : void 0;
   const frontmatter = buildFrontmatter({
     title: "Page not found",
     description: `No content is available at ${path}.`,
@@ -64,15 +65,18 @@ export default defineEventHandler(async (event) => {
     });
   }
   const { path, isExplicit, negotiation } = renderInfo;
-  const config = useRuntimeConfig(event)["nuxt-ai-ready"];
-  const resolveUrl = (path2) => withSiteUrl(event, path2);
+  const runtimeConfig = useRuntimeConfig(event);
+  const config = runtimeConfig["nuxt-ai-ready"];
+  const baseURL = runtimeConfig.app.baseURL;
+  const resolvePath = (path2) => toDeployedRoute(path2, baseURL);
+  const resolveUrl = (path2) => withSiteUrl(event, resolvePath(path2));
   const canonicalUrl = resolveUrl(path);
   if (negotiation === "html") {
     setNegotiationHeaders(event, path, config, resolveUrl);
     return;
   }
   if (!isExplicit) {
-    return sendRedirect(event, toMarkdownPath(path), 307);
+    return sendRedirect(event, resolvePath(toMarkdownPath(path)), 307);
   }
   const contentPage = await tryGetContentMarkdown(event, path).catch((e) => {
     logger.debug(`[markdown] Content lookup failed for ${path}`, e);
@@ -91,7 +95,7 @@ export default defineEventHandler(async (event) => {
 ${contentPage.markdown}`;
   }
   logger.debug(`[markdown] Fetching HTML for ${path}`);
-  const response = await event.fetch(path, {
+  const response = await event.fetch(resolvePath(path), {
     headers: { [INTERNAL_HEADER]: "1" },
     redirect: "manual"
   }).catch((e) => {
@@ -100,7 +104,7 @@ ${contentPage.markdown}`;
   });
   if (!response) {
     setMarkdownHeaders(event, path, config, resolveUrl);
-    return notFoundMarkdown(canonicalUrl, path, config);
+    return notFoundMarkdown(canonicalUrl, path, config, resolveUrl);
   }
   if (response.status >= 300 && response.status < 400) {
     const location = response.headers.get("location");
@@ -115,12 +119,12 @@ ${contentPage.markdown}`;
   }
   if (!response.ok) {
     setMarkdownHeaders(event, path, config, resolveUrl);
-    return notFoundMarkdown(canonicalUrl, path, config);
+    return notFoundMarkdown(canonicalUrl, path, config, resolveUrl);
   }
   const contentType = response.headers.get("content-type") || "";
   if (!contentType.includes("text/html")) {
     setMarkdownHeaders(event, path, config, resolveUrl);
-    return notFoundMarkdown(canonicalUrl, path, config);
+    return notFoundMarkdown(canonicalUrl, path, config, resolveUrl);
   }
   const html = await response.text();
   logger.debug(`[markdown] Fetched HTML for ${path} (${html.length} bytes)`);

package/dist/runtime/server/middleware/markdown.prerender.js

@@ -1,6 +1,7 @@
 import { createError, defineEventHandler } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
 import { withSiteUrl } from "#site-config/server/composables/utils";
+import { toDeployedRoute } from "../../route-path.js";
 import { logger } from "../logger.js";
 import { convertHtmlToMarkdown, extractLastUpdated, getMarkdownRenderInfo } from "../utils.js";
 import { tryGetContentMarkdown } from "../utils/content.js";
@@ -26,8 +27,10 @@ export default defineEventHandler(async (event) => {
   if (!renderInfo || "notAcceptable" in renderInfo)
     return;
   const { path } = renderInfo;
-  const runtimeConfig = useRuntimeConfig(event)["nuxt-ai-ready"];
-  const canonicalUrl = withSiteUrl(event, path);
+  const fullRuntimeConfig = useRuntimeConfig(event);
+  const runtimeConfig = fullRuntimeConfig["nuxt-ai-ready"];
+  const deployedPath = toDeployedRoute(path, fullRuntimeConfig.app.baseURL);
+  const canonicalUrl = withSiteUrl(event, deployedPath);
   const contentPage = await tryGetContentMarkdown(event, path).catch(() => null);
   if (contentPage) {
     logger.debug(`[markdown.prerender] Using content source for ${path} (${contentPage.markdown.length} bytes)`);
@@ -56,7 +59,7 @@ ${contentPage.markdown}`;
     logger.debug(`[markdown.prerender] Reusing prerendered HTML for ${path} (${html.length} bytes)`);
   } else {
     logger.debug(`[markdown.prerender] Fetching HTML for ${path}`);
-    const response = await event.fetch(path, { signal: AbortSignal.timeout(3e4) }).catch((err) => {
+    const response = await event.fetch(deployedPath, { signal: AbortSignal.timeout(3e4) }).catch((err) => {
       if (err?.name === "TimeoutError" || err?.name === "AbortError") {
         throw createError({
           statusCode: 504,

package/dist/runtime/server/routes/llms-full.txt.get.js

@@ -1,6 +1,8 @@
 import { eventHandler, sendIterable, setHeader, setResponseHeader } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
 import { getSiteConfig } from "#site-config/server/composables";
+import { withSiteUrl } from "#site-config/server/composables/utils";
+import { toDeployedRoute } from "../../route-path.js";
 import { countPages, streamPages } from "../db/queries.js";
 import { buildLlmsFullTxtHeader, formatPageForLlmsFullTxt } from "../utils/llms-full.js";
 export default eventHandler(async (event) => {
@@ -8,12 +10,15 @@ export default eventHandler(async (event) => {
     setHeader(event, "Content-Type", "text/plain; charset=utf-8");
     return "# llms-full.txt\n\nThis file is generated during prerender.";
   }
-  const config = useRuntimeConfig()["nuxt-ai-ready"];
+  const runtimeConfig = useRuntimeConfig(event);
+  const config = runtimeConfig["nuxt-ai-ready"];
   const siteConfig = getSiteConfig(event);
+  const baseURL = runtimeConfig.app.baseURL;
+  const canonicalSiteUrl = siteConfig.url ? withSiteUrl(event, toDeployedRoute("/", baseURL)) : void 0;
   const header = buildLlmsFullTxtHeader(
     {
       name: siteConfig.name,
-      url: siteConfig.url,
+      url: canonicalSiteUrl,
       description: siteConfig.description
     },
     config.llmsTxt

package/dist/runtime/server/utils/cloudflare.d.ts

@@ -17,5 +17,5 @@ export declare function hasAssets(event?: H3Event): boolean;
  * Falls back to $fetch with timeout to avoid self-fetch hangs on CF Workers.
  */
 export declare function fetchPublicAsset<T = unknown>(event: H3Event | undefined, path: string, options?: {
-    responseType?: 'json' | 'text' | 'arrayBuffer';
+    responseType?: 'json' | 'text' | 'arrayBuffer' | 'stream';
 }): Promise<T | null>;

package/dist/runtime/server/utils/cloudflare.js

@@ -19,6 +19,8 @@ export async function fetchPublicAsset(event, path, options) {
         return response.text().catch(() => null);
       if (responseType === "arrayBuffer")
         return response.arrayBuffer().catch(() => null);
+      if (responseType === "stream")
+        return response.body;
     }
     return null;
   }
@@ -27,6 +29,6 @@ export async function fetchPublicAsset(event, path, options) {
   return globalThis.$fetch(path, {
     baseURL: "/",
     signal: controller.signal,
-    responseType: responseType === "arrayBuffer" ? "arrayBuffer" : void 0
+    responseType: responseType === "arrayBuffer" || responseType === "stream" ? responseType : void 0
   }).catch(() => null).finally(() => clearTimeout(timeout));
 }

package/dist/runtime/server/utils/indexnow-shared.js

@@ -1,3 +1,4 @@
+import { joinURL } from "ufo";
 export const INDEXNOW_HOSTS = ["api.indexnow.org", "www.bing.com"];
 export function getIndexNowEndpoints() {
   const testEndpoint = process.env.INDEXNOW_TEST_ENDPOINT;
@@ -8,12 +9,12 @@ export function getIndexNowEndpoints() {
 }
 export function buildIndexNowBody(routes, key, siteUrl) {
   const urlList = routes.map(
-    (route) => route.startsWith("http") ? route : `${siteUrl}${route}`
+    (route) => route.startsWith("http") ? route : joinURL(siteUrl, route)
   );
   return {
     host: new URL(siteUrl).host,
     key,
-    keyLocation: `${siteUrl}/${key}.txt`,
+    keyLocation: joinURL(siteUrl, `${key}.txt`),
     urlList
   };
 }

package/dist/runtime/server/utils/link-header.js

@@ -15,9 +15,11 @@ function resolveHeaderUrl(path, resolveUrl) {
 export function buildLinkHeader(path, variant, config, resolveUrl) {
   const parts = [];
   if (variant === "html") {
-    parts.push(`<${encodePathForHeader(toMarkdownPath(path))}>; rel="alternate"; type="text/markdown"`);
+    const href = resolveHeaderUrl(toMarkdownPath(path), resolveUrl);
+    parts.push(`<${encodePathForHeader(href)}>; rel="alternate"; type="text/markdown"`);
   } else {
-    parts.push(`<${encodePathForHeader(path)}>; rel="alternate"; type="text/html"`);
+    const href = resolveHeaderUrl(path, resolveUrl);
+    parts.push(`<${encodePathForHeader(href)}>; rel="alternate"; type="text/html"`);
   }
   if (config.i18n) {
     const alternates = computeLocaleAlternates(path, config.i18n);

package/dist/runtime/server/utils/llms-full.js

@@ -1,9 +1,9 @@
+import { joinURL } from "ufo";
 import { normalizeLlmsTxtConfig } from "../../llms-txt-format.js";
-const RE_TRAILING_SLASH = /\/$/;
 const RE_FRONTMATTER = /^---\n[\s\S]*?\n---\n*/;
 const RE_HEADING = /^(#{1,6}) ([^\n]+)$/gm;
 export function formatPageForLlmsFullTxt(route, title, description, markdown, siteUrl) {
-  const canonicalUrl = siteUrl ? `${siteUrl.replace(RE_TRAILING_SLASH, "")}${route}` : route;
+  const canonicalUrl = siteUrl ? joinURL(siteUrl, route) : route;
   const heading = title && title !== route ? `### ${title}` : `### ${route}`;
   const content = markdown.replace(RE_FRONTMATTER, "").replace(RE_HEADING, (_, hashes, text) => `h${hashes.length}. ${text}`);
   const parts = [heading, ""];

package/dist/runtime/server/utils/sitemap.js

@@ -1,4 +1,4 @@
-import { isSitemapIndex, parseSitemapIndex, parseSitemapXml } from "@nuxtjs/sitemap/utils";
+import { parseSitemapStream } from "@nuxtjs/sitemap/utils";
 import { useRuntimeConfig } from "nitropack/runtime";
 import { withLeadingSlash } from "ufo";
 import { logger } from "../logger.js";
@@ -26,26 +26,26 @@ export function hasMultipleSitemaps(event) {
   const sitemaps = getSitemapsFromConfig(event);
   return sitemaps.length > 1;
 }
-function normalizeUrls(urls) {
-  return urls.map((entry) => {
-    if (typeof entry === "string")
-      return { loc: entry };
-    const e = entry;
-    return {
-      loc: e.loc,
-      lastmod: e.lastmod instanceof Date ? e.lastmod.toISOString() : e.lastmod
-    };
-  });
+function normalizeUrl(entry) {
+  if (typeof entry === "string")
+    return { loc: entry };
+  return {
+    loc: entry.loc,
+    lastmod: entry.lastmod instanceof Date ? entry.lastmod.toISOString() : entry.lastmod
+  };
+}
+function isSitemapXmlInput(value) {
+  return typeof value === "string" || value instanceof Uint8Array || typeof value === "object" && value !== null && "getReader" in value;
 }
 export async function fetchSitemapByRoute(event, route, depth = 0) {
   const config = useRuntimeConfig(event)["nuxt-ai-ready"];
   const fetchRoute = withLeadingSlash(route);
   const usePublicAsset = config.sitemapPrerendered && hasAssets(event);
   logger.debug(`[sitemap] Fetching ${fetchRoute} via ${usePublicAsset ? "ASSETS.fetch" : event ? "event.$fetch" : "globalThis.$fetch"}`);
-  let sitemapXml = null;
+  let sitemapInput = null;
   if (usePublicAsset) {
-    sitemapXml = await fetchPublicAsset(event, fetchRoute, { responseType: "text" });
-    if (!sitemapXml) {
+    sitemapInput = await fetchPublicAsset(event, fetchRoute, { responseType: "stream" });
+    if (!sitemapInput) {
       logger.warn(`[sitemap] Not found in ASSETS: ${fetchRoute}`);
       return { urls: [], error: "Not found in ASSETS" };
     }
@@ -53,38 +53,53 @@ export async function fetchSitemapByRoute(event, route, depth = 0) {
     try {
       const $fetch = event?.$fetch ?? globalThis.$fetch;
       const res = await $fetch(fetchRoute, {
-        responseType: "text",
+        responseType: "stream",
         timeout: FETCH_TIMEOUT
       });
-      if (!res || typeof res !== "string") {
+      if (!res) {
         logger.warn(`[sitemap] Empty response from ${fetchRoute}`);
         return { urls: [], error: "Empty response" };
       }
-      sitemapXml = res;
+      if (!isSitemapXmlInput(res)) {
+        logger.warn(`[sitemap] Invalid response body from ${fetchRoute}`);
+        return { urls: [], error: "Invalid response body" };
+      }
+      sitemapInput = res;
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       logger.warn(`[sitemap] Failed to fetch ${fetchRoute}: ${msg}`);
       return { urls: [], error: msg };
     }
   }
-  logger.debug(`[sitemap] Parsing sitemap XML (${sitemapXml.length} bytes)`);
-  if (isSitemapIndex(sitemapXml)) {
+  logger.debug(`[sitemap] Parsing sitemap XML stream`);
+  const urls = [];
+  const indexEntries = [];
+  let kind;
+  try {
+    for await (const parsed of parseSitemapStream(sitemapInput)) {
+      if (parsed._tag === "kind")
+        kind = parsed.kind;
+      else if (parsed._tag === "url")
+        urls.push(normalizeUrl(parsed.url));
+      else if (parsed._tag === "sitemap")
+        indexEntries.push(parsed.sitemap);
+      else
+        logger.warn(`[sitemap] ${fetchRoute}: ${parsed.warning.message}`);
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    logger.warn(`[sitemap] Failed to parse ${fetchRoute}: ${msg}`);
+    return { urls: [], error: msg };
+  }
+  if (kind === "index") {
     if (depth >= 3) {
       logger.warn(`[sitemap] Sitemap index nesting too deep at ${fetchRoute}, stopping`);
       return { urls: [] };
     }
-    let index;
-    try {
-      index = await parseSitemapIndex(sitemapXml);
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      logger.warn(`[sitemap] Failed to parse sitemap index ${fetchRoute}: ${msg}`);
-      return { urls: [], error: msg };
-    }
-    logger.debug(`[sitemap] ${fetchRoute} is a sitemap index with ${index.entries.length} children`);
+    logger.debug(`[sitemap] ${fetchRoute} is a sitemap index with ${indexEntries.length} children`);
     const allUrls = [];
     const childErrors = [];
-    for (const entry of index.entries) {
+    for (const entry of indexEntries) {
       const childRoute = entry.loc.startsWith("http") ? new URL(entry.loc).pathname : entry.loc;
       if (withLeadingSlash(childRoute) === fetchRoute)
         continue;
@@ -94,21 +109,12 @@ export async function fetchSitemapByRoute(event, route, depth = 0) {
         childErrors.push(`${withLeadingSlash(childRoute)}: ${error}`);
     }
     if (childErrors.length > 0) {
-      const msg = `${childErrors.length}/${index.entries.length} child sitemaps failed (${childErrors.join("; ")})`;
+      const msg = `${childErrors.length}/${indexEntries.length} child sitemaps failed (${childErrors.join("; ")})`;
       logger.warn(`[sitemap] Sitemap index ${fetchRoute}: ${msg}`);
       return { urls: allUrls, error: msg };
     }
     return { urls: allUrls };
   }
-  let result;
-  try {
-    result = await parseSitemapXml(sitemapXml);
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    logger.warn(`[sitemap] Failed to parse ${fetchRoute}: ${msg}`);
-    return { urls: [], error: msg };
-  }
-  const urls = normalizeUrls(result?.urls || []);
   logger.debug(`[sitemap] Found ${urls.length} URLs in ${fetchRoute}`);
   return { urls };
 }

package/dist/runtime/types.d.ts

@@ -260,11 +260,11 @@ export interface LlmsTxtLink {
 export interface LlmsTxtSection {
     /** The title of the section */
     title: string;
-    /** The description of the section (can be array for multiple paragraphs) */
+    /** Description rendered in the heading-free preamble, or in each optional link note (can be array for multiple paragraphs) */
     description?: string | string[];
     /** The links of the section */
     links?: LlmsTxtLink[];
-    /** Mark section as optional per llms.txt spec. Optional sections appear under `## Optional` and LLMs may skip them with shorter context windows. */
+    /** Mark links as optional per llms.txt spec. Links from all optional sections are flattened under `## Optional`. */
     optional?: boolean;
 }
 /**
@@ -273,7 +273,7 @@ export interface LlmsTxtSection {
 export interface LlmsTxtConfig {
     /** The sections of the documentation */
     sections?: LlmsTxtSection[];
-    /** Notes section (always appears at the end) */
+    /** Additional heading-free preamble notes rendered before file-list sections */
     notes?: string | string[];
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ai-ready",
   "type": "module",
-  "version": "1.5.5",
+  "version": "1.5.7",
   "description": "Best practice AI & LLM discoverability for Nuxt sites.",
   "author": {
     "name": "Harlan Wilton",
@@ -42,7 +42,7 @@
   "peerDependencies": {
     "@libsql/client": "^0.14.0",
     "@neondatabase/serverless": "^1.0.0",
-    "@nuxtjs/sitemap": ">=7.0.0",
+    "@nuxtjs/sitemap": ">=8.3.0",
     "better-sqlite3": "^11.0.0 || ^12.0.0"
   },
   "peerDependenciesMeta": {
@@ -57,18 +57,18 @@
     }
   },
   "dependencies": {
-    "@mdream/js": "^1.5.2",
+    "@mdream/js": "^1.5.3",
     "@nuxt/kit": "^4.5.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "defu": "^6.1.7",
     "drizzle-orm": "^0.45.2",
-    "mdream": "^1.5.2",
-    "nuxt-site-config": "^4.1.1",
-    "nuxtseo-shared": "^5.3.2",
+    "mdream": "^1.5.3",
+    "nuxt-site-config": "^4.1.2",
+    "nuxtseo-shared": "^5.3.3",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.1",
-    "site-config-stack": "^4.1.1",
+    "site-config-stack": "^4.1.2",
     "ufo": "^1.6.4",
     "uncrypto": "^0.1.3"
   },
@@ -81,8 +81,8 @@
     "@nuxt/test-utils": "^4.0.3",
     "@nuxtjs/eslint-config-typescript": "^12.1.0",
     "@nuxtjs/mcp-toolkit": "^0.18.0",
-    "@nuxtjs/robots": "^6.1.2",
-    "@nuxtjs/sitemap": "^8.2.2",
+    "@nuxtjs/robots": "^6.1.3",
+    "@nuxtjs/sitemap": "^8.3.0",
     "@types/better-sqlite3": "^7.6.13",
     "@vitest/coverage-v8": "^4.1.10",
     "@vue/test-utils": "^2.4.11",
@@ -92,15 +92,15 @@
     "eslint": "^10.7.0",
     "eslint-plugin-harlanzw": "^0.17.0",
     "execa": "^10.0.0",
-    "happy-dom": "^20.10.6",
+    "happy-dom": "^20.11.0",
     "nitropack": "^2.13.4",
     "nuxt": "^4.5.0",
-    "nuxt-site-config": "^4.1.1",
-    "nuxtseo-layer-devtools": "^5.3.2",
+    "nuxt-site-config": "^4.1.2",
+    "nuxtseo-layer-devtools": "^5.3.3",
     "playwright": "^1.61.1",
     "playwright-core": "^1.61.1",
     "tinyglobby": "^0.2.17",
-    "typescript": "^6.0.3",
+    "typescript": "6.0.3",
     "unbuild": "^3.6.1",
     "vitest": "^4.1.10",
     "vue": "^3.5.40",