@agentmarkup/astro 0.3.1 → 0.3.3

package/README.md

@@ -91,14 +91,18 @@ export default defineConfig({
 - Validates JSON-LD already present in page HTML
 - Generates `.md` mirrors from the final HTML output
 - Patches or creates `robots.txt` with AI crawler directives
-- Patches or creates `_headers` with `Content-Signal`
+- Patches or creates `_headers` with `Content-Signal` and canonical `Link` headers for markdown mirrors
 - Validates common schema and crawler mistakes at build time
 - Warns when a page looks like a thin client-rendered HTML shell
 - Re-exports `@agentmarkup/core` helpers for custom pipelines
 
 By default, the Astro adapter coexists with existing machine-readable assets. If a page already contains JSON-LD for a schema type, or the site already ships a curated `llms.txt` or matching crawler rules, those are preserved unless you opt into replacement.
 
-Markdown mirrors and `_headers` follow the same rule: existing files are preserved unless you opt into replacement with `markdownPages.replaceExisting` or `contentSignalHeaders.replaceExisting`.
+Markdown mirrors stay directly fetchable for agents, while their `_headers` entries point search engines back at the HTML page as canonical. Existing files are still preserved unless you opt into replacement with `markdownPages.replaceExisting` or `contentSignalHeaders.replaceExisting`.
+
+When markdown mirrors are enabled, the adapter also writes canonical `Link` headers for those `.md` files so search engines can keep the HTML route as the preferred indexed URL without making the markdown mirror unavailable to direct fetchers.
+
+When markdown mirrors are enabled, same-site page entries in `llms.txt` automatically point at the generated `.md` mirrors by default. Set `llmsTxt.preferMarkdownMirrors: false` if you want `llms.txt` to keep linking to HTML routes instead.
 
 ## Maintainer
 

package/dist/index.js

@@ -14,6 +14,7 @@ import {
   injectHeadContent,
   injectJsonLdTags,
   markdownFileNameFromHtmlFile,
+  patchMarkdownCanonicalHeaders,
   patchHeadersFile,
   normalizePagePath,
   patchRobotsTxt,
@@ -34,6 +35,8 @@ function agentmarkup(config) {
   let jsonLdPages = 0;
   let markdownPages = 0;
   let markdownPagesStatus = "none";
+  let markdownCanonicalHeadersCount = 0;
+  let markdownCanonicalHeadersStatus = "none";
   let crawlersConfigured = 0;
   let robotsTxtStatus = "none";
   let contentSignalHeadersStatus = "none";
@@ -96,6 +99,7 @@ function agentmarkup(config) {
         }
         if (isFeatureEnabled(config.markdownPages)) {
           let preservedMarkdownPages = 0;
+          const markdownCanonicalEntries = [];
           for (const htmlFile of htmlFiles) {
             const relativeHtmlPath = relative(outDir, htmlFile).replace(/\\/g, "/");
             const markdownFileName = markdownFileNameFromHtmlFile(relativeHtmlPath);
@@ -114,15 +118,38 @@ function agentmarkup(config) {
             const existingMarkdown = existingOutputMarkdown ?? (publicDir ? await readTextFileIfExists(join(publicDir, markdownFileName)) : null);
             if (existingMarkdown && !config.markdownPages?.replaceExisting) {
               preservedMarkdownPages += 1;
+              markdownCanonicalEntries.push({
+                markdownPath: `/${markdownFileName}`,
+                canonicalUrl: buildCanonicalUrl(config.site, pagePath)
+              });
               if (!existingOutputMarkdown) {
                 await writeFile(outputMarkdownPath, existingMarkdown, "utf8");
               }
               continue;
             }
             await writeFile(outputMarkdownPath, markdown, "utf8");
+            markdownCanonicalEntries.push({
+              markdownPath: `/${markdownFileName}`,
+              canonicalUrl: buildCanonicalUrl(config.site, pagePath)
+            });
             markdownPages += 1;
           }
           markdownPagesStatus = markdownPages > 0 ? "generated" : preservedMarkdownPages > 0 ? "preserved" : "none";
+          if (markdownCanonicalEntries.length > 0) {
+            const outputHeadersPath = join(outDir, "_headers");
+            const existingOutputHeaders = await readTextFileIfExists(outputHeadersPath);
+            const existingHeaders = existingOutputHeaders ?? (publicDir ? await readTextFileIfExists(join(publicDir, "_headers")) : null);
+            const patchedHeaders = patchMarkdownCanonicalHeaders(
+              existingHeaders,
+              markdownCanonicalEntries
+            );
+            const preserved = existingHeaders !== null && patchedHeaders === ensureTrailingNewline(existingHeaders);
+            markdownCanonicalHeadersCount = markdownCanonicalEntries.length;
+            markdownCanonicalHeadersStatus = preserved ? "preserved" : "generated";
+            if (!preserved || !existingOutputFileExists(outputHeadersPath)) {
+              await writeFile(outputHeadersPath, patchedHeaders, "utf8");
+            }
+          }
         }
         const llmsTxtContent = generateLlmsTxt(config);
         if (llmsTxtContent) {
@@ -180,7 +207,7 @@ function agentmarkup(config) {
             existingHeaders,
             config.contentSignalHeaders
           );
-          const preserved = existingHeaders !== null && patchedHeaders === existingHeaders;
+          const preserved = existingHeaders !== null && patchedHeaders === ensureTrailingNewline(existingHeaders);
           contentSignalHeadersStatus = preserved ? "preserved" : "generated";
           if (!preserved || !existingOutputFileExists(outputHeadersPath)) {
             await writeFile(outputHeadersPath, patchedHeaders, "utf8");
@@ -194,6 +221,8 @@ function agentmarkup(config) {
           jsonLdPages,
           markdownPages,
           markdownPagesStatus,
+          markdownCanonicalHeadersCount,
+          markdownCanonicalHeadersStatus,
           crawlersConfigured,
           robotsTxtStatus,
           contentSignalHeadersStatus,
@@ -229,6 +258,10 @@ function pagePathFromOutputFile(outDir, filePath) {
   const candidatePath = relativePath === "index.html" ? "/" : `/${relativePath}`;
   return normalizePagePath(candidatePath);
 }
+function buildCanonicalUrl(siteUrl, pagePath) {
+  const base = siteUrl.replace(/\/$/, "");
+  return pagePath === "/" ? `${base}/` : `${base}${pagePath}`;
+}
 function existingOutputFileExists(filePath) {
   return existsSync(filePath);
 }
@@ -240,6 +273,10 @@ function hasMarkdownAlternateLink(html) {
     html
   );
 }
+function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}
+`;
+}
 export {
   agentmarkup
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmarkup/astro",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Build-time llms.txt, JSON-LD, markdown mirrors, headers, AI crawler controls, and validation for Astro",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "dist"
   ],
   "dependencies": {
-    "@agentmarkup/core": "0.3.1"
+    "@agentmarkup/core": "0.3.2"
   },
   "peerDependencies": {
     "astro": ">=4.0.0"