@agent-seo/core 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# @agent-seo/core
|
|
2
|
+
|
|
3
|
+
Framework-agnostic HTML-to-Markdown transformation engine for AI-readable websites.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @agent-seo/core
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## What It Does
|
|
12
|
+
|
|
13
|
+
- **Detects 19 AI bots** via User-Agent (GPTBot, ClaudeBot, PerplexityBot, etc.)
|
|
14
|
+
- **Transforms HTML to Markdown** — Readability extracts content, Turndown converts to clean Markdown
|
|
15
|
+
- **YAML frontmatter** — title, description, URL, lang, last-modified
|
|
16
|
+
- **JSON-LD extraction** — structured data from `<script type="application/ld+json">`
|
|
17
|
+
- **Generates `/llms.txt`** — auto-discovers routes following the [llmstxt.org](https://llmstxt.org) spec
|
|
18
|
+
- **LRU cache** — in-memory caching of transformed results
|
|
19
|
+
|
|
20
|
+
## Usage
|
|
21
|
+
|
|
22
|
+
### Transform HTML to Markdown
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
import { transform } from '@agent-seo/core';
|
|
26
|
+
|
|
27
|
+
const result = await transform('<html>...</html>', {
|
|
28
|
+
url: 'https://example.com/about',
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
console.log(result.markdown);
|
|
32
|
+
// ---
|
|
33
|
+
// title: "About Us"
|
|
34
|
+
// description: "Learn more about our company"
|
|
35
|
+
// url: "https://example.com/about"
|
|
36
|
+
// ---
|
|
37
|
+
// # About Us
|
|
38
|
+
// ...
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Detect AI Bots
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
import { detectAgent, shouldServeMarkdown } from '@agent-seo/core';
|
|
45
|
+
|
|
46
|
+
const ctx = detectAgent(request.headers.get('user-agent'));
|
|
47
|
+
if (ctx.isAIBot) {
|
|
48
|
+
console.log(ctx.bot.name); // 'GPTBot'
|
|
49
|
+
console.log(ctx.bot.operator); // 'OpenAI'
|
|
50
|
+
console.log(ctx.bot.purpose); // 'training'
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// Or simply:
|
|
54
|
+
if (shouldServeMarkdown(userAgent, acceptHeader)) {
|
|
55
|
+
// serve markdown
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Generate llms.txt
|
|
60
|
+
|
|
61
|
+
```typescript
|
|
62
|
+
import { generateLlmsTxt, discoverNextRoutes } from '@agent-seo/core';
|
|
63
|
+
|
|
64
|
+
const routes = discoverNextRoutes('/path/to/app');
|
|
65
|
+
const result = generateLlmsTxt({
|
|
66
|
+
siteName: 'My App',
|
|
67
|
+
siteDescription: 'A brief description for AI systems.',
|
|
68
|
+
baseUrl: 'https://myapp.com',
|
|
69
|
+
}, routes);
|
|
70
|
+
|
|
71
|
+
console.log(result.llmsTxt);
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Edge Runtime
|
|
75
|
+
|
|
76
|
+
For edge/Cloudflare Workers (no JSDOM), use the lightweight edge export:
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import { detectAgent, shouldServeMarkdown } from '@agent-seo/core/edge';
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Framework Adapters
|
|
83
|
+
|
|
84
|
+
Use the framework-specific packages for zero-config integration:
|
|
85
|
+
|
|
86
|
+
- [`@agent-seo/next`](https://www.npmjs.com/package/@agent-seo/next) — Next.js
|
|
87
|
+
- [`@agent-seo/express`](https://www.npmjs.com/package/@agent-seo/express) — Express
|
|
88
|
+
- [`@agent-seo/fastify`](https://www.npmjs.com/package/@agent-seo/fastify) — Fastify
|
|
89
|
+
- [`@agent-seo/hono`](https://www.npmjs.com/package/@agent-seo/hono) — Hono
|
|
90
|
+
|
|
91
|
+
## License
|
|
92
|
+
|
|
93
|
+
MIT
|