@fullstackdatasolutions/articles 1.2.2 → 1.3.0

package/dist/server.js

@@ -95,8 +95,7 @@ function reportArticlesError(report) {
   articlesErrorHandler(report);
 }
 
-// src/markdown.ts
-var DEFAULT_LINK_TARGET_STRATEGY = "external-new-tab";
+// src/linkClassification.ts
 function isNonBrowserNavigationLink(href) {
   return /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href) && !href.startsWith("http://") && !href.startsWith("https://");
 }
@@ -114,6 +113,9 @@ function isExternalHttpLink(href, siteUrl) {
   if (!siteOrigin) return true;
   return getOrigin(href) !== siteOrigin;
 }
+
+// src/markdown.ts
+var DEFAULT_LINK_TARGET_STRATEGY = "external-new-tab";
 function shouldOpenInNewTab(href, options = {}) {
   var _a;
   if (!href || href.startsWith("#") || isNonBrowserNavigationLink(href)) return false;
@@ -429,6 +431,64 @@ function extractToc(markdown) {
     return headings;
   });
 }
+var QUESTION_OPENERS = /^(what|how|why|when|where|who|which|can|should|does|do|is|are|will|would|must)\b/i;
+function deriveFaqFromHeadings(markdown) {
+  const items = [];
+  const collector = createFaqCollector(items);
+  let inFence = false;
+  for (const line of markdown.split("\n")) {
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    collector.consume(line);
+  }
+  collector.flush();
+  return items;
+}
+var FENCE = /^\s*(```|~~~)/;
+var ANY_HEADING = /^#{1,6}\s/;
+function isSpace(char) {
+  return char === " " || char === "	";
+}
+function trimTrailingHashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "#") end--;
+  return value.slice(0, end).trimEnd();
+}
+function readQuestionHeading(line) {
+  if (!line.startsWith("##") || line.startsWith("###")) return null;
+  if (!isSpace(line[2])) return null;
+  const text = trimTrailingHashes(line.slice(3).trim());
+  if (!text.endsWith("?") || !QUESTION_OPENERS.test(text)) return null;
+  return text;
+}
+function createFaqCollector(items) {
+  let pending = null;
+  let buffer = [];
+  const flush = () => {
+    if (pending && buffer.length > 0) {
+      items.push({ question: pending, answer: buffer.join(" ").trim() });
+    }
+    pending = null;
+    buffer = [];
+  };
+  const consume = (line) => {
+    if (ANY_HEADING.test(line)) {
+      flush();
+      pending = readQuestionHeading(line);
+      return;
+    }
+    if (!pending) return;
+    if (line.trim() === "") {
+      if (buffer.length > 0) flush();
+      return;
+    }
+    buffer.push(line.trim());
+  };
+  return { consume, flush };
+}
 
 // src/server-articles.ts
 var articlesDirectory = path.join(
@@ -561,6 +621,58 @@ function parseHowToSteps(raw) {
 function parseOptionalString(raw) {
   return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : void 0;
 }
+function deriveFaq(markdownContent, config) {
+  if ((config == null ? void 0 : config.deriveFaqFromHeadings) !== true) return void 0;
+  const derived = deriveFaqFromHeadings(markdownContent);
+  return derived.length ? derived : void 0;
+}
+function resolveLastmod(rawLastmod, rawDate, filePath, config) {
+  const declared = parseDateField(rawLastmod);
+  if (declared) return declared;
+  if ((config == null ? void 0 : config.lastmodFallback) !== "fileMtime") return void 0;
+  try {
+    return parseDateField(fs.statSync(filePath).mtime);
+  } catch (e) {
+    return parseDateField(rawDate);
+  }
+}
+function resolveAiCrawl(raw, config) {
+  if (typeof raw === "boolean") return raw;
+  return (config == null ? void 0 : config.aiCrawlDefault) === true;
+}
+function parseEntityReferences(raw, config) {
+  if (!Array.isArray(raw)) return void 0;
+  const items = raw.map((item) => {
+    var _a, _b;
+    if (typeof item === "string") {
+      const key = item.trim();
+      if (!key) return null;
+      return (_b = (_a = config == null ? void 0 : config.entities) == null ? void 0 : _a[key]) != null ? _b : { name: key };
+    }
+    if (typeof item === "object" && item !== null && typeof item.name === "string") {
+      const entity = item;
+      const name = entity.name.trim();
+      if (!name) return null;
+      return entity.sameAs ? { name, sameAs: entity.sameAs } : { name };
+    }
+    return null;
+  }).filter((item) => item !== null);
+  return items.length ? items : void 0;
+}
+function parseCitations(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const items = raw.map((item) => {
+    if (typeof item === "string") return item.trim() ? { name: item.trim() } : null;
+    if (typeof item === "object" && item !== null && typeof item.name === "string") {
+      const citation = item;
+      const name = citation.name.trim();
+      if (!name) return null;
+      return citation.url ? { name, url: citation.url } : { name };
+    }
+    return null;
+  }).filter((item) => item !== null);
+  return items.length ? items : void 0;
+}
 function parseSeriesOrder(raw) {
   return typeof raw === "number" && Number.isFinite(raw) ? raw : void 0;
 }
@@ -637,6 +749,7 @@ function getAllAuthors(config) {
 }
 function getArticleSummary(slug, config) {
   return __async(this, null, function* () {
+    var _a;
     try {
       const found = findArticleFile(slug);
       if (!found) return null;
@@ -653,7 +766,7 @@ function getArticleSummary(slug, config) {
         title: data.title || slug.replaceAll("-", " "),
         excerpt: data.excerpt || "",
         date: parseDateField(data.date),
-        lastmod: parseDateField(data.lastmod),
+        lastmod: resolveLastmod(data.lastmod, data.date, found.filePath, config),
         author,
         authors,
         authorSlug: primaryAuthorProfile == null ? void 0 : primaryAuthorProfile.slug,
@@ -666,14 +779,17 @@ function getArticleSummary(slug, config) {
         tags: data.tags || [],
         contentType: found.contentType,
         draft: data.draft === true,
-        faq: parseFaqItems(data.faq),
+        faq: (_a = parseFaqItems(data.faq)) != null ? _a : deriveFaq(markdownContent, config),
         howTo: parseHowToSteps(data.howTo),
+        answer: parseOptionalString(data.answer),
+        about: parseEntityReferences(data.about, config),
+        citation: parseCitations(data.citation),
         canonicalUrl: typeof data.canonicalUrl === "string" ? data.canonicalUrl : void 0,
         articleType: typeof data.articleType === "string" ? data.articleType : void 0,
         series: typeof data.series === "string" ? data.series : void 0,
         seriesSlug: parseOptionalString(data.seriesSlug),
         seriesOrder: parseSeriesOrder(data.seriesOrder),
-        aiCrawl: data.aiCrawl === true,
+        aiCrawl: resolveAiCrawl(data.aiCrawl, config),
         searchTitle: parseOptionalString(data.searchTitle),
         searchDescription: parseOptionalString(data.searchDescription),
         socialTitle: parseOptionalString(data.socialTitle),
@@ -742,10 +858,10 @@ function getAdjacentArticles(currentSlug) {
     return { previous, next };
   });
 }
-function getArticleMarkdown(slug) {
+function getArticleMarkdown(slug, config) {
   return __async(this, null, function* () {
     try {
-      const summary = yield getArticleSummary(slug);
+      const summary = yield getArticleSummary(slug, config);
       if (!(summary == null ? void 0 : summary.aiCrawl)) return null;
       const found = findArticleFile(slug);
       if (!found) return null;
@@ -763,12 +879,180 @@ function getArticleMarkdown(slug) {
     }
   });
 }
-function getArticleMarkdownResponse(slug, config) {
+var AI_CRAWLERS = [
+  "GPTBot",
+  "ChatGPT-User",
+  "OAI-SearchBot",
+  "CCBot",
+  "ClaudeBot",
+  "Claude-User",
+  "Claude-SearchBot",
+  "anthropic-ai",
+  "PerplexityBot",
+  "Perplexity-User",
+  "Google-Extended",
+  "Applebot-Extended",
+  "Bytespider",
+  "Amazonbot",
+  "meta-externalagent",
+  "cohere-ai",
+  "DuckAssistBot",
+  "MistralAI-User"
+];
+function matchAiCrawler(userAgent) {
+  var _a;
+  if (!userAgent) return null;
+  const normalized = userAgent.toLowerCase();
+  return (_a = AI_CRAWLERS.find((crawler) => normalized.includes(crawler.toLowerCase()))) != null ? _a : null;
+}
+function buildMarkdownTwinHeader(article, config, body) {
+  var _a, _b;
+  const siteUrl = config.siteUrl.replace(/\/$/, "");
+  const firstLine = (_b = (_a = body.trimStart().split("\n", 1)[0]) == null ? void 0 : _a.trim()) != null ? _b : "";
+  const bodyRepeatsTitle = firstLine.toLowerCase() === `# ${article.title}`.toLowerCase();
+  const facts = [
+    `Source: ${siteUrl}/articles/${article.slug}`,
+    article.date ? `Published: ${article.date}` : "",
+    article.lastmod ? `Updated: ${article.lastmod}` : "",
+    config.showAuthor !== false && article.author ? `Author: ${article.author}` : "",
+    `Site: ${config.siteName}`
+  ].filter(Boolean);
+  const blocks = [
+    bodyRepeatsTitle ? "" : `# ${article.title}`,
+    article.excerpt ? `> ${article.excerpt}` : "",
+    facts.join("\n"),
+    article.answer ? `**Short answer:** ${article.answer}` : "",
+    "---"
+  ].filter((block) => block !== "");
+  return `${blocks.join("\n\n")}
+
+`;
+}
+function reportAiCrawl(slug, config, headers) {
+  var _a, _b;
+  if (!config.onAiCrawl) return;
+  const userAgent = (_a = headers == null ? void 0 : headers.get("user-agent")) != null ? _a : "";
+  try {
+    config.onAiCrawl({ slug, crawler: (_b = matchAiCrawler(userAgent)) != null ? _b : "unknown", userAgent });
+  } catch (error) {
+    reportArticlesError({
+      code: "ai-crawl-handler-failed",
+      message: "onAiCrawl handler threw.",
+      error,
+      context: { slug }
+    });
+  }
+}
+function buildListingMarkdown(heading, intro, articles, config) {
+  const siteUrl = config.siteUrl.replace(/\/$/, "");
+  const crawlable = articles.filter((article) => article.aiCrawl === true);
+  const entries = crawlable.map((article) => {
+    var _a;
+    const summary = (_a = article.answer) != null ? _a : article.excerpt;
+    const line = `- [${article.title}](${siteUrl}/articles/${article.slug}.md)`;
+    return summary ? `${line}: ${summary}` : line;
+  });
+  return [
+    `# ${heading}`,
+    "",
+    ...intro.flatMap((line) => [line, ""]),
+    `Source: ${siteUrl}`,
+    `Site: ${config.siteName}`,
+    "",
+    "---",
+    "",
+    ...entries.length > 0 ? entries : ["_No articles available._"],
+    ""
+  ].join("\n");
+}
+function getCategoryMarkdown(categorySlug, config) {
+  return __async(this, null, function* () {
+    var _a;
+    const articles = yield getArticlesByCategory(categorySlug, config);
+    if (articles.length === 0) return null;
+    const name = (_a = articles[0].categories.find((c) => categoryToSlug(c) === categorySlug)) != null ? _a : categorySlug;
+    const description = resolveCategoryDescription(categorySlug, config);
+    return buildListingMarkdown(name, description ? [description] : [], articles, config);
+  });
+}
+function resolveCategoryDescription(categorySlug, config) {
+  var _a, _b;
+  const entry = (_a = config.categoryDescriptions) == null ? void 0 : _a[categorySlug];
+  if (!entry) return void 0;
+  return typeof entry === "string" ? entry : (_b = entry.long) != null ? _b : entry.short;
+}
+function getAuthorMarkdown(authorSlug, config) {
+  return __async(this, null, function* () {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const author = getAuthorBySlug(authorSlug, config);
+    if (!author) return null;
+    const articles = yield getArticlesByAuthor(authorSlug, config);
+    const intro = [
+      (_a = author.promise) != null ? _a : "",
+      (_b = author.bio) != null ? _b : "",
+      ...((_c = author.servesWho) == null ? void 0 : _c.length) ? [`Writes for: ${author.servesWho.join(", ")}`] : [],
+      ...((_d = author.knowsAbout) == null ? void 0 : _d.length) ? [`Writes about: ${author.knowsAbout.join(", ")}`] : [],
+      ...((_e = author.credentials) == null ? void 0 : _e.length) ? ["## Stated experience", ...author.credentials.map((item) => `- ${item}`)] : [],
+      ...((_f = author.proof) == null ? void 0 : _f.length) ? [
+        "## Proof points",
+        ...author.proof.map(
+          (item) => item.url ? `- [${item.claim}](${item.url})` : `- ${item.claim}`
+        )
+      ] : [],
+      ...((_g = author.originStory) == null ? void 0 : _g.length) ? [
+        "## Background",
+        ...author.originStory.flatMap((section) => [
+          ...section.heading ? [`### ${section.heading}`] : [],
+          ...section.paragraphs
+        ])
+      ] : []
+    ].filter((line) => line.trim() !== "");
+    return buildListingMarkdown(author.name, intro, articles, config);
+  });
+}
+function getSeriesMarkdown(seriesSlug, config) {
+  return __async(this, null, function* () {
+    var _a;
+    const articles = yield getArticlesBySeries(seriesSlug, config);
+    if (articles.length === 0) return null;
+    const name = (_a = articles[0].series) != null ? _a : seriesSlug;
+    return buildListingMarkdown(name, [], articles, config);
+  });
+}
+function getMarkdownTwinResponse(slug, config, options) {
+  return __async(this, null, function* () {
+    const listing = yield resolveListingMarkdown(slug, config);
+    if (listing !== void 0) {
+      if (listing === null) return new Response("Not Found", { status: 404 });
+      reportAiCrawl(slug, config, options == null ? void 0 : options.headers);
+      return new Response(listing, { headers: LISTING_MARKDOWN_HEADERS });
+    }
+    return getArticleMarkdownResponse(slug, config, options);
+  });
+}
+var LISTING_MARKDOWN_HEADERS = {
+  "Content-Type": "text/markdown; charset=utf-8",
+  "Cache-Control": "public, max-age=3600, s-maxage=3600"
+};
+function resolveListingMarkdown(slug, config) {
   return __async(this, null, function* () {
-    const markdown = yield getArticleMarkdown(slug);
+    const [prefix, ...rest] = slug.split("/");
+    const key = rest.join("/");
+    if (!key) return void 0;
+    if (prefix === "category") return getCategoryMarkdown(key, config);
+    if (prefix === "authors") return getAuthorMarkdown(key, config);
+    if (prefix === "series") return getSeriesMarkdown(key, config);
+    return void 0;
+  });
+}
+function getArticleMarkdownResponse(slug, config, options) {
+  return __async(this, null, function* () {
+    const markdown = yield getArticleMarkdown(slug, config);
     if (markdown === null) return new Response("Not Found", { status: 404 });
-    const article = yield getArticleMetadata(slug);
-    return new Response(markdown, {
+    const article = yield getArticleMetadata(slug, config);
+    reportAiCrawl(slug, config, options == null ? void 0 : options.headers);
+    const body = article && config.markdownTwinHeader !== false ? `${buildMarkdownTwinHeader(article, config, markdown)}${markdown.trimStart()}` : markdown;
+    return new Response(body, {
       headers: __spreadValues({
         "Content-Type": "text/markdown; charset=utf-8",
         "Cache-Control": "public, max-age=3600, s-maxage=3600"
@@ -793,22 +1077,15 @@ function getArticleAiHeaders(article, config) {
     "X-Robots-Tag": "noai, noimageai"
   };
 }
-function getAiRobotsTxtRules() {
+function getAiRobotsTxtRules(config) {
   return __async(this, null, function* () {
-    const articles = yield getAllArticles();
+    const articles = yield getAllArticles(config);
     const blockedArticles = articles.filter((article) => article.aiCrawl !== true);
     if (blockedArticles.length === 0) return "";
-    const aiCrawlers = [
-      "GPTBot",
-      "ChatGPT-User",
-      "CCBot",
-      "ClaudeBot",
-      "Claude-User",
-      "PerplexityBot",
-      "Google-Extended"
-    ];
     const disallowRules = blockedArticles.map((article) => `Disallow: /articles/${article.slug}`).join("\n");
-    return aiCrawlers.map((crawler) => [`User-agent: ${crawler}`, disallowRules].join("\n")).join("\n\n");
+    return AI_CRAWLERS.map((crawler) => [`User-agent: ${crawler}`, disallowRules].join("\n")).join(
+      "\n\n"
+    );
   });
 }
 function searchArticles(query, config) {
@@ -948,6 +1225,7 @@ function getRelatedContent(article, config, limit = 3) {
 }
 
 // src/articlesConfig.ts
+var DEFAULT_PAGE_SIZE = 6;
 function breadcrumbsAreEnabled(config) {
   var _a;
   return config.breadcrumbs !== false && ((_a = config.breadcrumbs) == null ? void 0 : _a.show) !== false;
@@ -957,6 +1235,20 @@ function getBreadcrumbsConfig(config) {
   if (config.breadcrumbs === false) return {};
   return (_a = config.breadcrumbs) != null ? _a : {};
 }
+function getOrganizationId(config) {
+  return `${config.siteUrl.replace(/\/$/, "")}/#organization`;
+}
+function getWebSiteId(config) {
+  return `${config.siteUrl.replace(/\/$/, "")}/#website`;
+}
+function getPersonId(authorUrl) {
+  return `${authorUrl.replace(/\/$/, "")}#person`;
+}
+var DEFAULT_TITLE_TEMPLATE = "{title} | {siteName}";
+function formatPageTitle(title, config) {
+  var _a;
+  return ((_a = config.titleTemplate) != null ? _a : DEFAULT_TITLE_TEMPLATE).replaceAll("{title}", title).replaceAll("{siteName}", config.siteName);
+}
 
 // src/pagination.ts
 function getTotalPages(totalCount, pageSize) {
@@ -1004,10 +1296,11 @@ function isPageOutOfRange(page, totalPages) {
 function escapeXml(str) {
   return str.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
 }
-function generateRssFeed(articles, config) {
-  var _a;
+function generateRssFeed(articles, config, options) {
+  var _a, _b;
   const siteUrl = config.siteUrl.replace(/\/$/, "");
   const showAuthor = config.showAuthor !== false;
+  const fullContent = (options == null ? void 0 : options.fullContent) === true;
   const items = articles.map((article) => {
     const url = `${siteUrl}/articles/${article.slug}`;
     const pubDate = article.date ? new Date(article.date).toUTCString() : "";
@@ -1019,6 +1312,7 @@ function generateRssFeed(articles, config) {
       `      <guid isPermaLink="true">${url}</guid>`,
       pubDate ? `      <pubDate>${pubDate}</pubDate>` : "",
       article.excerpt ? `      <description><![CDATA[${article.excerpt}]]></description>` : "",
+      fullContent && article.htmlContent ? `      <content:encoded><![CDATA[${article.htmlContent}]]></content:encoded>` : "",
       showAuthor && article.author ? `      <author>${escapeXml(article.author)}</author>` : "",
       article.category ? `      <category><![CDATA[${article.category}]]></category>` : "",
       imageUrl ? `      <media:content url="${imageUrl}" medium="image" width="1200" height="630"/>` : "",
@@ -1027,17 +1321,82 @@ function generateRssFeed(articles, config) {
   }).join("\n");
   const description = (_a = config.description) != null ? _a : `${config.siteName} articles`;
   return `<?xml version="1.0" encoding="UTF-8" ?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/">
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
   <channel>
     <title><![CDATA[${config.siteName}]]></title>
     <link>${siteUrl}/articles</link>
     <description><![CDATA[${description}]]></description>
-    <language>en</language>
+    <language>${(_b = config.language) != null ? _b : "en"}</language>
     <atom:link href="${siteUrl}/articles/feed.xml" rel="self" type="application/rss+xml" />
 ${items}
   </channel>
 </rss>`;
 }
+function buildLlmsHeader(config) {
+  var _a;
+  const summary = (_a = config.description) != null ? _a : `${config.siteName} articles`;
+  return [`# ${config.siteName}`, "", `> ${summary}`, ""];
+}
+function generateLlmsTxt(articles, config) {
+  const siteUrl = config.siteUrl.replace(/\/$/, "");
+  const crawlable = articles.filter((article) => article.aiCrawl === true);
+  const byCategory = /* @__PURE__ */ new Map();
+  for (const article of crawlable) {
+    const category = article.category || "Articles";
+    const existing = byCategory.get(category);
+    if (existing) existing.push(article);
+    else byCategory.set(category, [article]);
+  }
+  const sections = [...byCategory.entries()].map(([category, categoryArticles]) => {
+    const lines = categoryArticles.map((article) => {
+      const url = `${siteUrl}/articles/${article.slug}.md`;
+      const summary = article.excerpt ? `: ${article.excerpt}` : "";
+      return `- [${article.title}](${url})${summary}`;
+    });
+    return [`## ${category}`, "", ...lines].join("\n");
+  });
+  return [
+    ...buildLlmsHeader(config),
+    ...sections.length > 0 ? sections : ["## Articles", "", "_No articles available._"],
+    ...buildLlmsListingSection(crawlable, config),
+    ""
+  ].join("\n");
+}
+function buildLlmsListingSection(articles, config) {
+  var _a;
+  const siteUrl = config.siteUrl.replace(/\/$/, "");
+  const categories = [...new Set(articles.flatMap((a) => {
+    var _a2;
+    return (_a2 = a.categories) != null ? _a2 : [];
+  }))].filter(Boolean);
+  const series = [...new Set(articles.map((a) => a.seriesSlug).filter(Boolean))];
+  const authors = Object.values((_a = config.authors) != null ? _a : {});
+  const lines = [
+    ...categories.map(
+      (name) => `- [${name}](${siteUrl}/articles/category/${categoryToSlug(name)}.md)`
+    ),
+    ...config.showAuthorPage === false ? [] : authors.map((a) => `- [${a.name}](${siteUrl}/articles/authors/${a.slug}.md)`),
+    ...series.map((slug) => `- [${slug}](${siteUrl}/articles/series/${slug}.md)`)
+  ];
+  if (lines.length === 0) return [];
+  return ["## Collections", "", ...lines];
+}
+function generateLlmsFullTxt(articles, config) {
+  return __async(this, null, function* () {
+    const crawlable = articles.filter((article) => article.aiCrawl === true);
+    const documents = yield Promise.all(
+      crawlable.map((article) => __async(this, null, function* () {
+        const body = yield getArticleMarkdown(article.slug, config);
+        if (body === null) return null;
+        return `${buildMarkdownTwinHeader(article, config, body)}${body.trimStart()}`;
+      }))
+    );
+    return [
+      ...buildLlmsHeader(config),
+      ...documents.filter((doc) => doc !== null)
+    ].join("\n");
+  });
+}
 function generateArticleStaticParams() {
   return getAvailableArticleSlugs().map((slug) => ({ slug }));
 }
@@ -1103,7 +1462,7 @@ function generateArticleMetadata(slug, config) {
     const markdownUrl = getArticleMarkdownUrl(article, config);
     const authorNames = getArticleAuthors(article, config).map((author) => author.name);
     return {
-      title: `${search.title} | ${config.siteName}`,
+      title: formatPageTitle(search.title, config),
       description,
       keywords: [...((_b = article.tags) != null ? _b : []).map((tag) => tag.toLowerCase())].join(", "),
       openGraph: __spreadProps(__spreadValues(__spreadValues(__spreadValues({
@@ -1157,7 +1516,7 @@ function generateArticlesIndexMetadata(config) {
   var _a, _b;
   const siteUrl = config.siteUrl.replace(/\/$/, "");
   const indexUrl = `${siteUrl}/articles`;
-  const title = `Articles | ${config.siteName}`;
+  const title = formatPageTitle("Articles", config);
   const description = (_b = (_a = config.hero) == null ? void 0 : _a.description) != null ? _b : `Expert analysis and insights from ${config.siteName}.`;
   return {
     title,
@@ -1205,7 +1564,7 @@ function generateCategoryMetadata(categorySlug, config) {
     const raw = (_a = config.categoryDescriptions) == null ? void 0 : _a[categorySlug];
     const fallback = `Browse ${articles.length} article${articles.length === 1 ? "" : "s"} in the ${categoryName} category.`;
     const description = typeof raw === "string" ? raw : (_b = raw == null ? void 0 : raw.short) != null ? _b : fallback;
-    const title = `${categoryName} Articles | ${config.siteName}`;
+    const title = formatPageTitle(`${categoryName} Articles`, config);
     return {
       title,
       description,
@@ -1249,7 +1608,7 @@ function generateSeriesMetadata(seriesSlug, config) {
     const siteUrl = config.siteUrl.replace(/\/$/, "");
     const seriesUrl = `${siteUrl}/articles/series/${seriesSlug}`;
     const description = `Follow the ${seriesName} series - ${articles.length} article${articles.length === 1 ? "" : "s"} on ${config.siteName}.`;
-    const title = `${seriesName} Series | ${config.siteName}`;
+    const title = formatPageTitle(`${seriesName} Series`, config);
     return {
       title,
       description,
@@ -1291,7 +1650,7 @@ function generateAuthorMetadata(authorSlug, config) {
     if (!author || config.showAuthorPage === false) return { title: "Author Not Found" };
     const siteUrl = config.siteUrl.replace(/\/$/, "");
     const authorUrl = (_a = author.url) != null ? _a : `${siteUrl}/articles/authors/${author.slug}`;
-    const title = `${author.name} Articles | ${config.siteName}`;
+    const title = formatPageTitle(`${author.name} Articles`, config);
     return {
       title,
       description: author.bio,
@@ -1473,17 +1832,41 @@ function resolveAuthorAvatar(author, config) {
   const siteUrl = config.siteUrl.replace(/\/$/, "");
   return `${siteUrl}/articles/authors/${author.slug}/${author.avatar.replace(/^\/+/, "")}`;
 }
+function newestArticleDate(articles) {
+  var _a;
+  let newest;
+  for (const article of articles) {
+    const stamp = (_a = article.lastmod) != null ? _a : article.date;
+    if (!stamp) continue;
+    const parsed = new Date(stamp);
+    if (Number.isNaN(parsed.getTime())) continue;
+    if (!newest || parsed > newest) newest = parsed;
+  }
+  return newest;
+}
+function paginationEntries(basePath, itemCount, pageSize, lastModified, priority) {
+  const totalPages = getTotalPages(itemCount, pageSize);
+  const entries = [];
+  for (let page = 2; page <= totalPages; page++) {
+    entries.push({
+      url: buildPageUrl(basePath, page),
+      lastModified,
+      changeFrequency: "weekly",
+      priority
+    });
+  }
+  return entries;
+}
 function getArticleSitemapEntries(baseUrlOrConfig) {
   return __async(this, null, function* () {
-    const baseUrl = (typeof baseUrlOrConfig === "string" ? baseUrlOrConfig : baseUrlOrConfig.siteUrl).replace(/\/$/, "");
+    var _a, _b;
+    const config = typeof baseUrlOrConfig === "string" ? void 0 : baseUrlOrConfig;
+    const baseUrl = ((_a = config == null ? void 0 : config.siteUrl) != null ? _a : baseUrlOrConfig).replace(/\/$/, "");
     try {
-      const [articles, categories] = yield Promise.all([
-        getAllArticles(typeof baseUrlOrConfig === "string" ? void 0 : baseUrlOrConfig),
-        getAllCategories()
-      ]);
+      const [articles, categories] = yield Promise.all([getAllArticles(config), getAllCategories()]);
       const articleEntries = articles.map((article) => {
-        var _a;
-        const dateStr = (_a = article.lastmod) != null ? _a : article.date;
+        var _a2;
+        const dateStr = (_a2 = article.lastmod) != null ? _a2 : article.date;
         const lastModified = dateStr ? new Date(dateStr) : void 0;
         return {
           url: `${baseUrl}/articles/${article.slug}`,
@@ -1494,16 +1877,86 @@ function getArticleSitemapEntries(baseUrlOrConfig) {
       });
       const categoryEntries = categories.map((cat) => ({
         url: `${baseUrl}/articles/category/${cat.slug}`,
-        lastModified: /* @__PURE__ */ new Date(),
+        lastModified: newestArticleDate(
+          articles.filter(
+            (article) => {
+              var _a2;
+              return ((_a2 = article.categories) != null ? _a2 : []).some((name) => categoryToSlug(name) === cat.slug);
+            }
+          )
+        ),
         changeFrequency: "weekly",
         priority: 0.7
       }));
-      const authorEntries = typeof baseUrlOrConfig === "string" || baseUrlOrConfig.showAuthorPage === false ? [] : getAllAuthors(baseUrlOrConfig).map((author) => ({
+      const authors = config && config.showAuthorPage !== false ? getAllAuthors(config) : [];
+      const authorEntries = authors.map((author) => ({
         url: `${baseUrl}/articles/authors/${author.slug}`,
+        lastModified: newestArticleDate(
+          articles.filter(
+            (article) => getArticleAuthors(article, config).some((profile) => profile.slug === author.slug)
+          )
+        ),
         changeFrequency: "monthly",
         priority: 0.6
       }));
-      return [...articleEntries, ...categoryEntries, ...authorEntries];
+      const seriesSlugs = [...new Set(articles.map((a) => a.seriesSlug).filter(Boolean))];
+      const seriesEntries = seriesSlugs.map((seriesSlug) => ({
+        url: `${baseUrl}/articles/series/${seriesSlug}`,
+        lastModified: newestArticleDate(articles.filter((a) => a.seriesSlug === seriesSlug)),
+        changeFrequency: "weekly",
+        priority: 0.6
+      }));
+      const pageEntries = [];
+      if ((config == null ? void 0 : config.listingPagination) === "pages") {
+        const pageSize = (_b = config.pageSize) != null ? _b : DEFAULT_PAGE_SIZE;
+        pageEntries.push(
+          ...paginationEntries(
+            `${baseUrl}/articles`,
+            articles.length,
+            pageSize,
+            newestArticleDate(articles),
+            0.5
+          )
+        );
+        for (const cat of categories) {
+          const inCategory = articles.filter(
+            (article) => {
+              var _a2;
+              return ((_a2 = article.categories) != null ? _a2 : []).some((name) => categoryToSlug(name) === cat.slug);
+            }
+          );
+          pageEntries.push(
+            ...paginationEntries(
+              `${baseUrl}/articles/category/${cat.slug}`,
+              inCategory.length,
+              pageSize,
+              newestArticleDate(inCategory),
+              0.4
+            )
+          );
+        }
+        for (const author of authors) {
+          const byAuthor = articles.filter(
+            (article) => getArticleAuthors(article, config).some((profile) => profile.slug === author.slug)
+          );
+          pageEntries.push(
+            ...paginationEntries(
+              `${baseUrl}/articles/authors/${author.slug}`,
+              byAuthor.length,
+              pageSize,
+              newestArticleDate(byAuthor),
+              0.4
+            )
+          );
+        }
+      }
+      return [
+        ...articleEntries,
+        ...categoryEntries,
+        ...authorEntries,
+        ...seriesEntries,
+        ...pageEntries
+      ];
     } catch (e) {
       return [];
     }
@@ -1512,6 +1965,7 @@ function getArticleSitemapEntries(baseUrlOrConfig) {
 
 // src/renderMdx.tsx
 import React from "react";
+import Link from "next/link";
 import * as devRuntime from "react/jsx-dev-runtime";
 import * as runtime from "react/jsx-runtime";
 import { evaluate } from "@mdx-js/mdx";
@@ -1527,6 +1981,19 @@ function makeImgComponent(basePath) {
     return React.createElement("img", __spreadValues({ src: resolvedSrc, alt }, props));
   };
 }
+function isInternalNavigableHref(href, siteUrl) {
+  if (!href || href.startsWith("#") || isNonBrowserNavigationLink(href)) return false;
+  return !isExternalHttpLink(href, siteUrl);
+}
+function makeLinkComponent(siteUrl) {
+  return function MdxLink(_a) {
+    var _b = _a, { href, children } = _b, props = __objRest(_b, ["href", "children"]);
+    if (typeof href === "string" && isInternalNavigableHref(href, siteUrl)) {
+      return React.createElement(Link, __spreadValues({ href }, props), children);
+    }
+    return /* @__PURE__ */ jsx("a", __spreadProps(__spreadValues({ href }, props), { children }));
+  };
+}
 function renderMdxSource(source, basePath, config) {
   return __async(this, null, function* () {
     const isDevelopment = process.env.NODE_ENV === "development";
@@ -1541,8 +2008,10 @@ function renderMdxSource(source, basePath, config) {
       ]
     }));
     const Content = mdxModule.default;
-    const internalComponents = basePath ? { img: makeImgComponent(basePath) } : void 0;
-    const components = internalComponents || (config == null ? void 0 : config.mdxComponents) ? __spreadValues(__spreadValues({}, internalComponents), config == null ? void 0 : config.mdxComponents) : void 0;
+    const internalComponents = __spreadValues({
+      a: makeLinkComponent(config == null ? void 0 : config.siteUrl)
+    }, basePath ? { img: makeImgComponent(basePath) } : {});
+    const components = __spreadValues(__spreadValues({}, internalComponents), config == null ? void 0 : config.mdxComponents);
     return /* @__PURE__ */ jsx(Content, { components });
   });
 }
@@ -1661,8 +2130,32 @@ function ArticleTOC({ toc, className }) {
   );
 }
 
+// src/ArticleAnswer.tsx
+import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
+function ArticleAnswer({
+  article,
+  label = "The short answer",
+  className
+}) {
+  var _a;
+  if (!((_a = article.answer) == null ? void 0 : _a.trim())) return null;
+  return /* @__PURE__ */ jsxs3(
+    "aside",
+    {
+      className: `mb-8 rounded-lg border-l-4 border-primary bg-muted/40 px-6 py-4 ${className != null ? className : ""}`,
+      style: { borderLeftWidth: "4px" },
+      children: [
+        /* @__PURE__ */ jsx4("p", { className: "mb-2 text-sm font-semibold uppercase tracking-wide text-muted-foreground", children: label }),
+        /* @__PURE__ */ jsx4("p", { className: "text-base leading-relaxed", children: article.answer })
+      ]
+    }
+  );
+}
+
 // src/validateArticles.ts
 var UNSAFE_URL_SCHEME = /^\s*(javascript|data|vbscript):/i;
+var THIN_CONTENT_WORDS = 300;
+var STALE_CONTENT_MONTHS = 18;
 var SEARCH_TITLE_MAX = 60;
 var SEARCH_DESCRIPTION_MAX = 160;
 var SOCIAL_TITLE_MAX = 95;
@@ -1806,12 +2299,15 @@ function checkRequiredFrontmatter(articles) {
   }
   return issues;
 }
-function checkDiscoveryFieldLengths(articles) {
+function checkDiscoveryFieldLengths(articles, config) {
+  var _a, _b;
   const issues = [];
   for (const article of articles) {
+    const effectiveTitle = formatPageTitle((_a = article.searchTitle) != null ? _a : article.title, config);
+    const effectiveDescription = (_b = article.searchDescription) != null ? _b : article.excerpt;
     const checks = [
-      [article.searchTitle, "search-title-too-long", SEARCH_TITLE_MAX],
-      [article.searchDescription, "search-description-too-long", SEARCH_DESCRIPTION_MAX],
+      [effectiveTitle, "effective-title-too-long", SEARCH_TITLE_MAX],
+      [effectiveDescription, "effective-description-too-long", SEARCH_DESCRIPTION_MAX],
       [article.socialTitle, "social-title-too-long", SOCIAL_TITLE_MAX],
       [article.socialDescription, "social-description-too-long", SOCIAL_DESCRIPTION_MAX]
     ];
@@ -1828,6 +2324,101 @@ function checkDiscoveryFieldLengths(articles) {
   }
   return issues;
 }
+function checkAnswerability(articles) {
+  var _a, _b, _c;
+  const issues = [];
+  for (const article of articles) {
+    const hasQuestionHeading = ((_a = article.toc) != null ? _a : []).some(
+      (item) => item.depth === 2 && item.text.trim().endsWith("?")
+    );
+    if (!article.answer && !((_b = article.faq) == null ? void 0 : _b.length) && !hasQuestionHeading) {
+      issues.push({
+        severity: "warning",
+        code: "no-answer",
+        message: "Article has no `answer`, no `faq`, and no question-shaped heading - nothing for an answer engine to lift.",
+        articleSlug: article.slug
+      });
+    }
+    if (article.wordCount !== void 0 && article.wordCount < THIN_CONTENT_WORDS) {
+      issues.push({
+        severity: "warning",
+        code: "thin-content",
+        message: `Article is ${article.wordCount} words (under ${THIN_CONTENT_WORDS}).`,
+        articleSlug: article.slug
+      });
+    }
+    if (!((_c = article.about) == null ? void 0 : _c.length)) {
+      issues.push({
+        severity: "warning",
+        code: "missing-about",
+        message: "Article has no `about` entity references.",
+        articleSlug: article.slug
+      });
+    }
+  }
+  return issues;
+}
+function checkEntityReferences(articles, config) {
+  var _a;
+  const registry = config.entities;
+  if (!registry) return [];
+  const known = new Set(Object.values(registry).map((entity) => entity.name));
+  const issues = [];
+  for (const article of articles) {
+    for (const entity of (_a = article.about) != null ? _a : []) {
+      if (!known.has(entity.name) && !entity.sameAs) {
+        issues.push({
+          severity: "warning",
+          code: "unknown-entity",
+          message: `about entry "${entity.name}" is not in config.entities and has no sameAs.`,
+          articleSlug: article.slug
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkStaleContent(articles, now) {
+  var _a;
+  const cutoff = new Date(now);
+  cutoff.setMonth(cutoff.getMonth() - STALE_CONTENT_MONTHS);
+  const issues = [];
+  for (const article of articles) {
+    const stamp = (_a = article.lastmod) != null ? _a : article.date;
+    if (!stamp) continue;
+    const parsed = new Date(stamp);
+    if (Number.isNaN(parsed.getTime())) continue;
+    if (parsed < cutoff) {
+      issues.push({
+        severity: "warning",
+        code: "stale-content",
+        message: `Last updated ${stamp}, over ${STALE_CONTENT_MONTHS} months ago.`,
+        articleSlug: article.slug
+      });
+    }
+  }
+  return issues;
+}
+function checkOrphanArticles(articles) {
+  const bodies = articles.filter((article) => typeof article.content === "string");
+  if (bodies.length === 0) return [];
+  const issues = [];
+  for (const article of articles) {
+    const needle = `/articles/${article.slug}`;
+    const linked = bodies.some(
+      (other) => other.slug !== article.slug && other.content.includes(needle)
+    );
+    if (!linked) {
+      issues.push({
+        severity: "warning",
+        code: "orphan-article",
+        message: "No other article links to this one.",
+        articleSlug: article.slug
+      });
+    }
+  }
+  return issues;
+}
 function checkCategorySlugs(articles) {
   var _a;
   const issues = [];
@@ -1851,7 +2442,8 @@ function checkCategorySlugs(articles) {
   }
   return issues;
 }
-function validateArticles(articles, config) {
+function validateArticles(articles, config, options) {
+  var _a;
   const errors = [
     ...checkDuplicateCanonicalUrls(articles),
     ...checkAuthorReferences(articles, config),
@@ -1861,15 +2453,19 @@ function validateArticles(articles, config) {
   ];
   const warnings = [
     ...checkRequiredFrontmatter(articles),
-    ...checkDiscoveryFieldLengths(articles),
+    ...checkDiscoveryFieldLengths(articles, config),
+    ...checkAnswerability(articles),
+    ...checkEntityReferences(articles, config),
+    ...checkStaleContent(articles, (_a = options == null ? void 0 : options.now) != null ? _a : /* @__PURE__ */ new Date()),
+    ...checkOrphanArticles(articles),
     ...checkCategorySlugs(articles)
   ];
   return { ok: errors.length === 0, errors, warnings };
 }
-function validateAllArticles(config) {
+function validateAllArticles(config, options) {
   return __async(this, null, function* () {
     const articles = yield getAllArticles(config);
-    return validateArticles(articles, config);
+    return validateArticles(articles, config, options);
   });
 }
 
@@ -1882,16 +2478,21 @@ function emitArticleEvent(handler, event) {
   }
 }
 export {
+  AI_CRAWLERS,
+  ArticleAnswer,
   ArticleContent,
   ArticleTOC,
   buildArticleBreadcrumbs,
   buildAuthorBreadcrumbs,
   buildCategoryBreadcrumbs,
+  buildMarkdownTwinHeader,
   buildPageUrl,
   buildPaginationLinks,
   categoryToSlug,
+  deriveFaqFromHeadings,
   emitArticleEvent,
   extractToc,
+  formatPageTitle,
   generateArticleMetadata,
   generateArticleStaticParams,
   generateArticlesIndexMetadata,
@@ -1903,6 +2504,8 @@ export {
   generateCategoryPageMetadata,
   generateCategoryStaticParams,
   generateListingPageStaticParams,
+  generateLlmsFullTxt,
+  generateLlmsTxt,
   generateRssFeed,
   generateSeriesMetadata,
   generateSeriesStaticParams,
@@ -1923,16 +2526,24 @@ export {
   getArticlesByCategory,
   getArticlesBySeries,
   getAuthorBySlug,
+  getAuthorMarkdown,
   getAvailableArticleSlugs,
   getBreadcrumbsConfig,
+  getCategoryMarkdown,
   getContentSlotBoundaries,
+  getMarkdownTwinResponse,
+  getOrganizationId,
   getPath,
   getPathArticles,
+  getPersonId,
   getRelatedArticlesByCategory,
   getRelatedContent,
+  getSeriesMarkdown,
   getTotalPages,
+  getWebSiteId,
   isPageOutOfRange,
   markdownToHtml,
+  matchAiCrawler,
   paginateArticles,
   parsePageParam,
   resolveAuthorAvatar,