KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

agentmarkup

★ 20 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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, Next.js, and Nuxt websites, plus a framework-agnostic CLI for any static output.

## 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
- `packages/audit` — the publishable `@agentmarkup/audit`, a runtime CLI that fetches a live URL as each major AI crawler, diffs against a browser, and reports machine-readability findings (CI-friendly)
- `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

```bash
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:

```ts
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, including the canonical `Content-Signal` policy alongside the crawler rules
- patch or create `_headers`, or merge server header rules, with the `Content-Signal` header 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, Next.js, and Nuxt adapters, plus a framework-agnostic CLI
- 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` policy generation in `robots.txt` and the `_headers` header
- deterministic validation checks
- reusable generation and validation helpers for custom prerender pipelines

## Local Development

```bash
pnpm install
pnpm lint
pnpm test
pnpm typecheck
pnpm build
```

Package details live in [packages/vite/README.md](./packages/vite/README.md), [packages/astro/README.md](./packages/astro/README.md), [packages/next/README.md](./packages/next/README.md), [packages/cli/README.md](./packages/cli/README.md), [packages/nuxt/README.md](./packages/nuxt/README.md), and [packages/core/README.md](./packages/core/README.md).
Contribution guidelines live in [CONTRIBUTING.md](./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:

```bash
npx skills add agentmarkup/agentmarkup --skill agentmarkup
```

Preview with GitHub CLI:

```bash
gh skill preview agentmarkup/agentmarkup agentmarkup
```

Invoke it without installing:

```bash
npx skills use agentmarkup/agentmarkup --skill agentmarkup
```

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

Example prompts:

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

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

```text
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

Used in production on [Anima Felix](https://animafelix.com).

agentmarkup

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README