agentmarkup

Build-time llms.txt, optional llms-full.txt, optional A2A Agent Cards, JSON-LD, markdown mirrors, AI crawler controls, and validation for Vite, Astro, and Next.js websites.

What This Repo Contains

• packages/core — the framework-agnostic engine used by adapters and manual pipelines
• packages/vite — the publishable @agentmarkup/vite adapter
• packages/astro — the publishable @agentmarkup/astro adapter
• packages/next — the publishable @agentmarkup/next adapter
• packages/cli — the publishable @agentmarkup/cli, a framework-agnostic command that runs agentmarkup over any built static output directory (with a CI-friendly check command)
• packages/nuxt — the publishable @agentmarkup/nuxt module for prerendered / nuxt generate output
• website — the dogfooding landing page built against the workspace package boundary
• examples/vite-react — a minimal example app for local verification and onboarding

Quick Start

Choose the adapter that owns your final output:

• @agentmarkup/vite for Vite
• @agentmarkup/astro for Astro
• @agentmarkup/next for Next.js
• @agentmarkup/nuxt for Nuxt (prerendered / nuxt generate output)
• @agentmarkup/cli for any other built static site, or as a CI check

pnpm add -D @agentmarkup/vite
# or: pnpm add -D @agentmarkup/astro
# or: pnpm add -D @agentmarkup/next
# or: pnpm add -D @agentmarkup/nuxt
# or: pnpm add -D @agentmarkup/cli

Vite example:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { agentmarkup } from '@agentmarkup/vite';

export default defineConfig({
  plugins: [
    react(),
    agentmarkup({
      site: 'https://example.com',
      name: 'Example',
      description: 'Structured, machine-readable metadata for your site.',
      llmsTxt: {
        sections: [
          {
            title: 'Pages',
            entries: [
              {
                title: 'Docs',
                url: '/docs',
                description: 'Documentation and guides',
              },
            ],
          },
        ],
      },
      markdownPages: {
        enabled: true,
      },
      contentSignalHeaders: {
        enabled: true,
      },
      globalSchemas: [
        {
          preset: 'webSite',
          name: 'Example',
          url: 'https://example.com',
        },
      ],
      aiCrawlers: {
        GPTBot: 'allow',
        ClaudeBot: 'allow',
      },
    }),
  ],
});

On build, the adapters can:

• emit optional /.well-known/agent-card.json for existing A2A services
• emit llms.txt
• emit optional llms-full.txt with inlined same-site markdown context
• inject the homepage llms.txt discovery link automatically
• inject JSON-LD into generated HTML
• validate JSON-LD already present in page HTML
• emit page-level .md mirrors from final HTML output when a cleaner agent-facing fetch path is useful
• patch or create robots.txt with AI crawler directives
• patch or create _headers, or merge server header rules, with Content-Signal and canonical Link headers for markdown mirrors
• report deterministic validation warnings and errors in the terminal, including markdown alternate-link and mirror-coverage issues

By default, agentmarkup coexists with existing machine-readable assets. If a site already has a curated llms.txt, matching crawler rules, or hand-authored JSON-LD for a schema type, those are preserved unless you explicitly opt into replacement.

Optional A2A Agent Card support is intentionally narrow. If you already run a real A2A-compatible agent service, agentmarkup can emit a static /.well-known/agent-card.json discovery file for that service from the same build pipeline. It does not implement the A2A runtime protocol or agent server itself. When you enable agentCard, provide a version, at least one supportedInterfaces entry, and a non-empty description through either the top-level description or agentCard.description.

Markdown mirrors are optional. They are usually most useful for thin, noisy, or client-rendered HTML where the raw page is a poor fetch target for agents. When enabled, same-site page entries in llms.txt default to the generated .md URLs so cold agents discover the cleaner fetch path first. Set llmsTxt.preferMarkdownMirrors: false if you want llms.txt to keep pointing at HTML routes instead.

If your site already has a custom prerender or post-build step, @agentmarkup/core exposes reusable llms.txt, JSON-LD, and robots.txt helpers so you can keep one final output pipeline instead of duplicating that logic.

@agentmarkup/vite is best when Vite owns the final HTML files. Meta-frameworks that render or prerender final HTML after Vite's build phases may still benefit from llms.txt and robots.txt, but they usually need either @agentmarkup/core in the final output step or a dedicated adapter to guarantee JSON-LD reaches the deployed HTML.

@agentmarkup/next is best when Next owns the final build output. Static export gets the full post-build file flow, prerendered and server deployments still get generated assets plus header integration, but fully dynamic SSR routes are still a per-route integration point: if Next does not emit build-time HTML for that route, use the re-exported @agentmarkup/core helpers directly inside app code.

@agentmarkup/nuxt is best when Nuxt prerenders your pages (nuxt generate or prerender: true). It hooks Nitro after prerendering and processes the emitted .output/public HTML. Fully dynamic SSR routes that never emit build-time HTML are not patched automatically; use the re-exported @agentmarkup/core helpers in app code for those.

@agentmarkup/cli is framework-agnostic: point it at any built static output directory (agentmarkup generate ./dist) to run the same pipeline without an adapter, or use agentmarkup check ./dist as a CI gate that fails on machine-readability errors. Useful for static site generators without a dedicated adapter and for validating already-deployed output.

Current Features

• Vite, Astro, and Next.js adapters
• optional A2A Agent Card generation plus config and output validation
• llms.txt generation
• optional llms-full.txt generation
• automatic llms.txt discovery-link injection
• JSON-LD injection
• existing JSON-LD validation
• markdown page generation
• markdown alternate-link and mirror-coverage validation
• schema presets for website and ecommerce basics
• AI crawler robots.txt management
• Content-Signal header generation
• deterministic validation checks
• reusable generation and validation helpers for custom prerender pipelines

Local Development

pnpm install
pnpm lint
pnpm test
pnpm typecheck
pnpm build

Package details live in packages/vite/README.md, packages/astro/README.md, packages/next/README.md, packages/cli/README.md, packages/nuxt/README.md, and packages/core/README.md. Contribution guidelines live in CONTRIBUTING.md.

Website deploys are manual via ./deploy/website-deploy.sh.

Public Agent Skill

This repo ships a public Agent Skills / skills.sh-compatible skill at skills/agentmarkup.

Use it to install AgentMarkup in another JavaScript web repo, configure it from user preferences, audit generated output, and implement fixes for llms.txt, llms-full.txt, JSON-LD, markdown mirrors, AI crawler rules, and headers.

Install with the skills CLI:

npx skills add agentmarkup/agentmarkup --skill agentmarkup

Preview with GitHub CLI:

gh skill preview agentmarkup/agentmarkup agentmarkup

Invoke it without installing:

npx skills use agentmarkup/agentmarkup --skill agentmarkup

After installing it, ask your coding agent to use $agentmarkup inside the target website repo.

Example prompts:

Use $agentmarkup to install AgentMarkup in this repo, configure it for my public site, run an audit, and implement the fixes.

Use $agentmarkup to add llms.txt, JSON-LD, markdown mirrors, AI crawler rules, and Content-Signal headers to this Vite/Astro/Next.js site.

Use $agentmarkup to inspect this custom post-build pipeline, choose @agentmarkup/core if appropriate, and wire the generated assets into the final deploy output.

Maintainer

Copyright (c) 2026 Sebastian Cochinescu. MIT License.

Used in production on Anima Felix.