@agentmarkup/astro 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sebastian Cochinescu and Anima Felix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @agentmarkup/astro
+
+Build-time `llms.txt`, JSON-LD, AI crawler `robots.txt`, and validation for Astro websites.
+
+## Install
+
+```bash
+pnpm add -D @agentmarkup/astro
+```
+
+## Usage
+
+```ts
+import { defineConfig } from 'astro/config';
+import { agentmarkup } from '@agentmarkup/astro';
+
+export default defineConfig({
+  integrations: [
+    agentmarkup({
+      site: 'https://example.com',
+      name: 'Example',
+      description: 'Machine-readable metadata for an Astro site.',
+      llmsTxt: {
+        sections: [
+          {
+            title: 'Documentation',
+            entries: [
+              {
+                title: 'Getting Started',
+                url: '/docs/getting-started',
+                description: 'Setup guide and first steps',
+              },
+            ],
+          },
+        ],
+      },
+      globalSchemas: [
+        {
+          preset: 'webSite',
+          name: 'Example',
+          url: 'https://example.com',
+        },
+        {
+          preset: 'organization',
+          name: 'Example Inc.',
+          url: 'https://example.com',
+          logo: 'https://example.com/logo.png',
+        },
+      ],
+      pages: [
+        {
+          path: '/faq',
+          schemas: [
+            {
+              preset: 'faqPage',
+              url: 'https://example.com/faq',
+              questions: [
+                {
+                  question: 'Do you ship internationally?',
+                  answer: 'Yes.',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      aiCrawlers: {
+        GPTBot: 'allow',
+        ClaudeBot: 'allow',
+        PerplexityBot: 'allow',
+        'Google-Extended': 'allow',
+      },
+      validation: {
+        warnOnMissingSchema: true,
+      },
+    }),
+  ],
+});
+```
+
+## What It Does
+
+- Injects JSON-LD into built HTML pages during the Astro build
+- Generates `/llms.txt` from config
+- Patches or creates `robots.txt` with AI crawler directives
+- Validates common schema and crawler mistakes at build time
+- 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.
+
+## Maintainer
+
+Copyright (c) 2026 [Sebastian Cochinescu](https://www.cochinescu.com). MIT License.
+
+Used in production on [Anima Felix](https://animafelix.com).
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { AstroIntegration } from 'astro';
+import { AgentMarkupConfig } from '@agentmarkup/core';
+export * from '@agentmarkup/core';
+
+declare function agentmarkup(config: AgentMarkupConfig): AstroIntegration;
+
+export { agentmarkup };

package/dist/index.js

@@ -0,0 +1,162 @@
+// src/index.ts
+import { existsSync } from "fs";
+import { readdir, readFile, writeFile } from "fs/promises";
+import { join, relative } from "path";
+import { fileURLToPath } from "url";
+import {
+  collectSchemasForPage,
+  filterJsonLdByExistingTypes,
+  generateJsonLdTags,
+  generateLlmsTxt,
+  hasExistingJsonLdScripts,
+  injectJsonLdTags,
+  normalizePagePath,
+  patchRobotsTxt,
+  presetToJsonLd,
+  printReport,
+  validateLlmsTxt,
+  validateRobotsTxt,
+  validateSchema
+} from "@agentmarkup/core";
+export * from "@agentmarkup/core";
+function agentmarkup(config) {
+  const validationResults = [];
+  let llmsTxtEntries = 0;
+  let llmsTxtSections = 0;
+  let llmsTxtStatus = "none";
+  let jsonLdPages = 0;
+  let crawlersConfigured = 0;
+  let robotsTxtStatus = "none";
+  let publicDir;
+  return {
+    name: "agentmarkup",
+    hooks: {
+      "astro:config:done": ({ config: resolvedConfig }) => {
+        publicDir = fileURLToPath(resolvedConfig.publicDir);
+      },
+      "astro:build:done": async ({ dir }) => {
+        const outDir = fileURLToPath(dir);
+        const htmlFiles = await findHtmlFiles(outDir);
+        for (const htmlFile of htmlFiles) {
+          const pagePath = pagePathFromOutputFile(outDir, htmlFile);
+          const html = await readFile(htmlFile, "utf8");
+          const schemas = collectSchemasForPage(config, pagePath);
+          const hasExistingJsonLd = hasExistingJsonLdScripts(html);
+          if (schemas.length === 0) {
+            if (pagePath && config.validation?.warnOnMissingSchema && !config.validation.disabled && !hasExistingJsonLd) {
+              validationResults.push({
+                severity: "warning",
+                message: "No structured data configured for this page",
+                path: pagePath
+              });
+            }
+            continue;
+          }
+          const jsonLdObjects = schemas.map(presetToJsonLd);
+          const injectables = config.jsonLd?.replaceExistingTypes ? jsonLdObjects : filterJsonLdByExistingTypes(jsonLdObjects, html);
+          if (!config.validation?.disabled) {
+            for (const schema of schemas) {
+              validationResults.push(...validateSchema(schema, pagePath));
+            }
+          }
+          if (injectables.length === 0) {
+            continue;
+          }
+          const tags = generateJsonLdTags(injectables);
+          await writeFile(htmlFile, injectJsonLdTags(html, tags), "utf8");
+          jsonLdPages += 1;
+        }
+        const llmsTxtContent = generateLlmsTxt(config);
+        if (llmsTxtContent) {
+          const outputLlmsPath = join(outDir, "llms.txt");
+          const existingOutputLlms = await readTextFileIfExists(outputLlmsPath);
+          const existingLlms = existingOutputLlms ?? (publicDir ? await readTextFileIfExists(join(publicDir, "llms.txt")) : null);
+          if (existingLlms && !config.llmsTxt?.replaceExisting) {
+            llmsTxtStatus = "preserved";
+            if (!existingOutputLlms) {
+              await writeFile(outputLlmsPath, existingLlms, "utf8");
+            }
+            if (!config.validation?.disabled) {
+              validationResults.push(...validateLlmsTxt(existingLlms));
+            }
+          } else {
+            llmsTxtStatus = "generated";
+            llmsTxtSections = config.llmsTxt?.sections.length ?? 0;
+            llmsTxtEntries = config.llmsTxt?.sections.reduce(
+              (sum, section) => sum + section.entries.length,
+              0
+            ) ?? 0;
+            await writeFile(outputLlmsPath, llmsTxtContent, "utf8");
+            if (!config.validation?.disabled) {
+              validationResults.push(...validateLlmsTxt(llmsTxtContent));
+            }
+          }
+        }
+        if (config.aiCrawlers) {
+          const crawlerEntries = Object.entries(config.aiCrawlers).filter(
+            ([, value]) => value !== void 0
+          );
+          crawlersConfigured = crawlerEntries.length;
+          let existingRobots = await readTextFileIfExists(join(outDir, "robots.txt"));
+          if (!existingRobots && publicDir) {
+            existingRobots = await readTextFileIfExists(join(publicDir, "robots.txt"));
+          }
+          if (existingRobots && !config.validation?.disabled) {
+            validationResults.push(
+              ...validateRobotsTxt(existingRobots, config.aiCrawlers)
+            );
+          }
+          const patched = patchRobotsTxt(existingRobots, config.aiCrawlers);
+          const preserved = existingRobots !== null && patched === existingRobots;
+          robotsTxtStatus = preserved ? "preserved" : "patched";
+          const outputRobotsPath = join(outDir, "robots.txt");
+          if (!preserved || !existingOutputFileExists(outputRobotsPath)) {
+            await writeFile(outputRobotsPath, patched, "utf8");
+          }
+        }
+        printReport({
+          label: "@agentmarkup/astro",
+          llmsTxtEntries,
+          llmsTxtSections,
+          llmsTxtStatus,
+          jsonLdPages,
+          crawlersConfigured,
+          robotsTxtStatus,
+          validationResults
+        });
+      }
+    }
+  };
+}
+async function readTextFileIfExists(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return readFile(filePath, "utf8");
+}
+async function findHtmlFiles(rootDir) {
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  const htmlFiles = [];
+  for (const entry of entries) {
+    const entryPath = join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      htmlFiles.push(...await findHtmlFiles(entryPath));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".html")) {
+      htmlFiles.push(entryPath);
+    }
+  }
+  return htmlFiles.sort();
+}
+function pagePathFromOutputFile(outDir, filePath) {
+  const relativePath = relative(outDir, filePath).replace(/\\/g, "/");
+  const candidatePath = relativePath === "index.html" ? "/" : `/${relativePath}`;
+  return normalizePagePath(candidatePath);
+}
+function existingOutputFileExists(filePath) {
+  return existsSync(filePath);
+}
+export {
+  agentmarkup
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@agentmarkup/astro",
+  "version": "0.2.0",
+  "description": "Build-time llms.txt, JSON-LD, and AI crawler controls for Astro",
+  "type": "module",
+  "license": "MIT",
+  "author": "Sebastian Cochinescu <hello@animafelix.com> (https://animafelix.com)",
+  "homepage": "https://agentmarkup.dev",
+  "bugs": {
+    "url": "https://github.com/agentmarkup/agentmarkup/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentmarkup/agentmarkup",
+    "directory": "packages/astro"
+  },
+  "keywords": [
+    "astro",
+    "llms-txt",
+    "json-ld",
+    "schema-org",
+    "structured-data",
+    "robots-txt",
+    "ai-crawler",
+    "machine-readable"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@agentmarkup/core": "0.2.0"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "devDependencies": {
+    "astro": "^5.7.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "prebuild": "pnpm -C ../core build",
+    "build": "tsup",
+    "predev": "pnpm -C ../core build",
+    "dev": "tsup --watch",
+    "pretest": "pnpm -C ../core build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ test/",
+    "pretypecheck": "pnpm -C ../core build",
+    "typecheck": "tsc --noEmit"
+  }
+}