npm - @ontosdk/next - Versions diffs - 1.2.0 → 1.3.0 - Mend

@ontosdk/next 1.2.0 → 1.3.0

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.

Files changed (53) hide show

package/JSON_LD_GUIDE.md ADDED Viewed

@@ -0,0 +1,403 @@
+# Automatic JSON-LD Schema Injection Guide
+The OntoProvider now automatically injects JSON-LD structured data schemas based on your page configuration. **Zero manual JSON-LD writing required** - just configure your routes and the SDK does the rest.
+## Why JSON-LD Matters for AI
+JSON-LD (JavaScript Object Notation for Linked Data) is a lightweight format that helps AI agents:
+- **Understand your content** with high confidence
+- **Extract structured data** (pricing, products, methodology)
+- **Reduce hallucinations** by providing authoritative schema markup
+- **Score higher** on AIO metrics (worth 25 points in our scoring algorithm)
+## Quick Start
+### 1. Import Your Config
+```tsx
+// app/layout.tsx
+import { OntoProvider } from '@ontosdk/next/provider';
+import config from '../onto.config';
+export default function RootLayout({ children }) {
+  return (
+    <OntoProvider baseUrl="https://example.com" config={config}>
+      <html>
+        <head />
+        <body>{children}</body>
+      </html>
+    </OntoProvider>
+  );
+}
+```
+### 2. Configure Page Types
+```typescript
+// onto.config.ts
+import type { OntoConfig } from '@ontosdk/next';
+const config: OntoConfig = {
+  name: 'My Site',
+  summary: 'Description',
+  baseUrl: 'https://example.com',
+  routes: [
+    {
+      path: '/score',
+      description: 'AIO Score Calculator',
+      pageType: 'scoring' // ← Automatically injects Methodology schema
+    },
+    {
+      path: '/about',
+      description: 'About us',
+      pageType: 'about' // ← Automatically injects Organization schema
+    }
+  ],
+  organization: {
+    name: 'My Company',
+    description: 'What we do',
+    url: 'https://example.com',
+    logo: 'https://example.com/logo.png'
+  }
+};
+export default config;
+```
+### 3. That's It!
+The OntoProvider automatically:
+1. Detects the current page path
+2. Matches it against your route configuration
+3. Generates the appropriate JSON-LD schema
+4. Injects it into the page `<head>`
+No manual `<script type="application/ld+json">` tags needed!
+## Supported Page Types
+### `pageType: 'scoring'`
+**Use for**: AIO score calculators, methodology pages, scoring tools
+**Generates**: [HowTo Schema](https://schema.org/HowTo) explaining the AIO scoring methodology
+**Includes**:
+- 4-step methodology (Content Negotiation, Token Efficiency, Structured Data, Semantic HTML)
+- Standard AIO weights (40%, 35%, 25%, bonus)
+- Detailed explanations for each metric
+**Example output**:
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "AIO Score Calculation Methodology",
+  "description": "AI Optimization (AIO) Score measures how well a website is optimized for AI agents...",
+  "step": [
+    {
+      "@type": "HowToStep",
+      "name": "Content Negotiation",
+      "text": "Check if the site responds to Accept: text/markdown header. Weight: 40%...",
+      "position": 1
+    },
+    // ... 3 more steps
+  ]
+}
+```
+**When to use**:
+- `/score` - Score calculator pages
+- `/methodology` - Explanation of scoring system
+- `/calculator` - Any page with a scoring/grading tool
+### `pageType: 'about'`
+**Use for**: About pages, company info, team pages
+**Generates**: [AboutPage Schema](https://schema.org/AboutPage) + [Organization Schema](https://schema.org/Organization)
+**Includes**:
+- Organization name, description, URL
+- Logo, founding date (if provided)
+- Nested organization entity
+**Example output**:
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "AboutPage",
+  "name": "About My Company",
+  "url": "https://example.com/about",
+  "description": "Company description from config",
+  "mainEntity": {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    "name": "My Company",
+    "url": "https://example.com",
+    "description": "What we do",
+    "logo": "https://example.com/logo.png",
+    "foundingDate": "2024-01-01"
+  }
+}
+```
+**When to use**:
+- `/about` - Company about page
+- `/about-us` - Team/company info
+- `/company` - Organization details
+### `pageType: 'default'` (or omitted)
+**Use for**: All other pages
+**Generates**: Nothing - no automatic JSON-LD injection
+Use this for pages where you want to manually control JSON-LD or don't need structured data.
+## Configuration Reference
+### Route Configuration
+```typescript
+interface OntoRoute {
+  path: string;           // URL path (e.g., '/score')
+  description: string;    // What this page contains
+  pageType?: PageType;    // 'scoring' | 'about' | 'default'
+}
+```
+### Organization Configuration
+Required for `pageType: 'about'` to work properly:
+```typescript
+organization?: {
+  name: string;          // Required: Organization name
+  description?: string;  // Optional: What you do
+  url?: string;         // Optional: Company website
+  logo?: string;        // Optional: Logo URL (use absolute URL)
+  foundingDate?: string; // Optional: ISO date format (YYYY-MM-DD)
+}
+```
+## Complete Example
+```typescript
+// onto.config.ts
+import type { OntoConfig } from '@ontosdk/next';
+const config: OntoConfig = {
+  name: 'BuildOnto',
+  summary: 'Next.js infrastructure for AI-optimized websites',
+  baseUrl: 'https://buildonto.dev',
+  routes: [
+    {
+      path: '/',
+      description: 'Homepage',
+      pageType: 'default'
+    },
+    {
+      path: '/score',
+      description: 'AIO Score Calculator - grade your AI optimization',
+      pageType: 'scoring'
+    },
+    {
+      path: '/about',
+      description: 'About BuildOnto and our mission',
+      pageType: 'about'
+    },
+    {
+      path: '/docs',
+      description: 'Documentation and guides'
+      // No pageType = 'default', no automatic JSON-LD
+    }
+  ],
+  organization: {
+    name: 'BuildOnto',
+    description: 'Making websites AI-ready with zero-config infrastructure',
+    url: 'https://buildonto.dev',
+    logo: 'https://buildonto.dev/logo.png',
+    foundingDate: '2024-01-01'
+  }
+};
+export default config;
+```
+```tsx
+// app/layout.tsx
+import { OntoProvider } from '@ontosdk/next/provider';
+import config from '../onto.config';
+export default function RootLayout({ children }) {
+  return (
+    <OntoProvider baseUrl="https://buildonto.dev" config={config}>
+      <html lang="en">
+        <head />
+        <body>{children}</body>
+      </html>
+    </OntoProvider>
+  );
+}
+```
+Now visit `/score` or `/about` and view source - you'll see the JSON-LD automatically injected!
+## AIO Scoring Weights
+The `pageType: 'scoring'` schema includes the official AIO scoring methodology:
+| Metric | Weight | Max Penalty | Description |
+|--------|--------|-------------|-------------|
+| **Content Negotiation** | 40% | -30 points | Accept: text/markdown support |
+| **Token Efficiency** | 35% | -30 points | HTML size vs visible text ratio |
+| **Structured Data** | 25% | -25 points | JSON-LD presence (this feature!) |
+| **Semantic HTML** | Bonus | -15 points | `<main>`, `<article>` tags |
+By using this SDK with automatic JSON-LD injection, you instantly gain **+25 points** on the AIO score!
+## Validation
+### Test Your Schema
+1. Visit your page in development: `http://localhost:3000/score`
+2. View page source (Ctrl+U / Cmd+U)
+3. Look for `<script type="application/ld+json">`
+4. Copy the JSON content
+5. Validate at [Google's Rich Results Test](https://search.google.com/test/rich-results)
+### Check with cURL
+```bash
+# Fetch as an AI bot
+curl -H "User-Agent: GPTBot" http://localhost:3000/score | grep "application/ld+json"
+```
+## Advanced Usage
+### Manual Schema Generation
+If you need custom schemas beyond the built-in types:
+```typescript
+import { generateAIOMethodologySchema } from '@ontosdk/next';
+const schema = generateAIOMethodologySchema(config, 'https://example.com/score');
+console.log(JSON.stringify(schema, null, 2));
+```
+### Custom Page Types
+Want to add your own page types? Extend the config:
+```typescript
+// Create a custom schema generator
+function generateProductSchema(config, url) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: config.name,
+    url: url
+  };
+}
+// Use it manually in your component
+import { serializeSchema } from '@ontosdk/next';
+const jsonLd = serializeSchema(generateProductSchema(config, pageUrl));
+return (
+  <script
+    type="application/ld+json"
+    dangerouslySetInnerHTML={{ __html: jsonLd }}
+  />
+);
+```
+## Migration from Manual JSON-LD
+If you currently have manual JSON-LD:
+**Before** (manual):
+```tsx
+export default function AboutPage() {
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: JSON.stringify({
+            '@context': 'https://schema.org',
+            '@type': 'AboutPage',
+            name: 'About Us',
+            // ... lots of manual JSON
+          })
+        }}
+      />
+      <main>{/* content */}</main>
+    </>
+  );
+}
+```
+**After** (automatic):
+```tsx
+// onto.config.ts
+routes: [
+  { path: '/about', description: 'About us', pageType: 'about' }
+]
+// app/layout.tsx - just wrap once
+<OntoProvider config={config} baseUrl="https://example.com">
+  {children}
+</OntoProvider>
+```
+## Benefits
+✅ **Zero Manual Work**: Configure once, works everywhere
+✅ **Type-Safe**: Full TypeScript support with intellisense
+✅ **Consistent**: Same schema structure across all pages
+✅ **Maintainable**: Update in one place (config) instead of per-page
+✅ **AIO Optimized**: Schemas designed specifically for AI agents
+✅ **Schema.org Compliant**: Follows official standards
+✅ **Validation Ready**: Works with Google Rich Results Test
+## Troubleshooting
+### Schema not appearing?
+1. **Check config path**: Make sure you're importing the config correctly
+2. **Verify route match**: Path must exactly match (including trailing slashes)
+3. **Check pageType**: Must be explicitly set to 'scoring' or 'about'
+4. **Organization missing**: For 'about' pages, ensure `organization` is configured
+### Wrong schema type?
+- Double-check the `pageType` value in your route config
+- Ensure you're passing the config prop to OntoProvider
+### TypeScript errors?
+```bash
+npm install @ontosdk/next@latest
+```
+Make sure you're on the latest version with schema support.
+## Resources
+- [Schema.org: HowTo](https://schema.org/HowTo)
+- [Schema.org: AboutPage](https://schema.org/AboutPage)
+- [Schema.org: Organization](https://schema.org/Organization)
+- [Google Rich Results Test](https://search.google.com/test/rich-results)
+- [AIO Score Documentation](https://buildonto.dev/docs/aio-score)
+---
+**Next Steps**: Check out [LLMS_TXT_GUIDE.md](./LLMS_TXT_GUIDE.md) for automatic llms.txt generation!

package/LLMS_TXT_GUIDE.md ADDED Viewed

@@ -0,0 +1,297 @@
+# Dynamic llms.txt Generation Guide
+The Onto middleware now supports **dynamic llms.txt generation** from your `onto.config.ts` file. This means you never have to manually create or update an `llms.txt` file—it's generated on-the-fly from your configuration.
+## What is llms.txt?
+`llms.txt` is a standardized file format that provides AI agents (like ChatGPT, Claude, and Perplexity) with a concise, structured overview of your website. It follows a simple Markdown format and helps AI systems understand:
+- What your site is about
+- Where the most important content is located
+- What resources are available
+**Key Benefits:**
+- AI agents get accurate, up-to-date information about your site
+- No manual file maintenance—generated from config
+- Follows the official llms.txt specification
+- Automatically served to AI crawlers by the middleware
+## Setup
+### 1. Create `onto.config.ts`
+Create a file named `onto.config.ts` in your project root:
+```typescript
+import { OntoConfig } from '@ontosdk/next';
+const config: OntoConfig = {
+  name: 'My Project',
+  summary: 'A brief description of what your project does and who it serves.',
+  baseUrl: 'https://example.com',
+  routes: [
+    { path: '/', description: 'Homepage' },
+    { path: '/docs', description: 'Documentation' },
+    { path: '/api', description: 'API reference' }
+  ]
+};
+export default config;
+```
+### 2. Middleware Configuration
+If you've already installed the Onto middleware, you're done! The middleware automatically:
+1. Detects requests to `/llms.txt`
+2. Loads your `onto.config.ts`
+3. Generates the llms.txt content dynamically
+4. Returns it with proper headers (`Content-Type: text/plain`)
+No additional configuration needed.
+## Configuration Schema
+### Required Fields
+#### `name` (string)
+The name of your project or website. Used as the H1 heading in llms.txt.
+```typescript
+name: 'Acme Corp Documentation'
+```
+#### `summary` (string)
+A concise summary of your project. Should contain key information that helps AI agents understand the purpose and scope of your site. Displayed as a blockquote in llms.txt.
+```typescript
+summary: 'Comprehensive documentation for the Acme API. Includes REST endpoints, SDKs, and integration guides for Python, JavaScript, and Go.'
+```
+#### `baseUrl` (string)
+The base URL of your website. Used to construct full URLs for routes.
+```typescript
+baseUrl: 'https://docs.acme.com'
+```
+### Optional Fields
+#### `routes` (array)
+Key routes that AI agents should know about. Each route includes:
+- `path`: The URL path (e.g., `/docs/api`)
+- `description`: What this route contains
+```typescript
+routes: [
+  {
+    path: '/docs/getting-started',
+    description: 'Quick start guide for new developers'
+  },
+  {
+    path: '/docs/api/reference',
+    description: 'Complete API endpoint reference'
+  },
+  {
+    path: '/blog',
+    description: 'Technical blog and release notes'
+  }
+]
+```
+#### `externalLinks` (array)
+Links to external resources like GitHub, status pages, or community forums.
+```typescript
+externalLinks: [
+  {
+    title: 'GitHub Repository',
+    url: 'https://github.com/acme/sdk',
+    description: 'Source code and issue tracker'
+  },
+  {
+    title: 'API Status',
+    url: 'https://status.acme.com'
+  }
+]
+```
+#### `sections` (array)
+Custom markdown sections to add additional context. Each section has:
+- `heading`: The section title
+- `content`: Markdown content
+```typescript
+sections: [
+  {
+    heading: 'About',
+    content: 'Acme provides cloud infrastructure for modern applications...'
+  },
+  {
+    heading: 'Key Features',
+    content: `- **Fast**: Sub-millisecond response times
+- **Secure**: SOC 2 Type II certified
+- **Scalable**: Handles millions of requests per second`
+  }
+]
+```
+## Example Output
+With the following config:
+```typescript
+const config: OntoConfig = {
+  name: 'Acme Documentation',
+  summary: 'API docs and guides for Acme Cloud Platform',
+  baseUrl: 'https://docs.acme.com',
+  routes: [
+    { path: '/api', description: 'API reference' },
+    { path: '/guides', description: 'Integration guides' }
+  ]
+};
+```
+The generated `/llms.txt` will be:
+```markdown
+# Acme Documentation
+> API docs and guides for Acme Cloud Platform
+## Key Routes
+- [/api](https://docs.acme.com/api): API reference
+- [/guides](https://docs.acme.com/guides): Integration guides
+```
+## Advanced Usage
+### TypeScript Support
+Full TypeScript support with type checking:
+```typescript
+import type { OntoConfig } from '@ontosdk/next';
+const config: OntoConfig = {
+  name: 'My Site',
+  summary: 'Description',
+  baseUrl: 'https://example.com',
+  // TypeScript will validate all fields
+};
+export default config;
+```
+### Environment-Specific Configuration
+Use environment variables for different deployment environments:
+```typescript
+const config: OntoConfig = {
+  name: 'My App',
+  summary: 'A great application',
+  baseUrl: process.env.NEXT_PUBLIC_BASE_URL || 'https://example.com',
+  routes: [
+    { path: '/', description: 'Home' },
+    ...(process.env.NODE_ENV === 'production'
+      ? [{ path: '/enterprise', description: 'Enterprise features' }]
+      : []
+    )
+  ]
+};
+export default config;
+```
+### Dynamic Routes
+Generate routes programmatically:
+```typescript
+const docPages = ['getting-started', 'authentication', 'webhooks'];
+const config: OntoConfig = {
+  name: 'API Docs',
+  summary: 'Developer documentation',
+  baseUrl: 'https://api.example.com',
+  routes: [
+    { path: '/', description: 'API overview' },
+    ...docPages.map(page => ({
+      path: `/docs/${page}`,
+      description: `Guide: ${page.replace('-', ' ')}`
+    }))
+  ]
+};
+export default config;
+```
+## Fallback Behavior
+The middleware implements intelligent fallback:
+1. **With config**: Generates llms.txt dynamically from `onto.config.ts`
+2. **Without config**: Falls back to static `public/llms.txt` if it exists
+3. **On error**: Logs error and attempts to serve static file
+This ensures your site always has an llms.txt, even if configuration fails.
+## Caching
+Generated llms.txt responses include optimal cache headers:
+```
+Content-Type: text/plain; charset=utf-8
+Cache-Control: public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400
+```
+This means:
+- Cached for 1 hour in browsers/CDNs
+- Stale content can be served for up to 24 hours while revalidating
+- Reduces server load and improves response times
+## Debugging
+To verify your llms.txt is being generated correctly:
+1. **Start your dev server**: `npm run dev`
+2. **Visit**: `http://localhost:3000/llms.txt`
+3. **Check console**: Look for `[Onto] Failed to generate llms.txt:` errors
+If you see your generated content, you're all set!
+## Migration from Static llms.txt
+If you currently have a static `public/llms.txt` file:
+1. Create `onto.config.ts` with your site information
+2. Test that `/llms.txt` is being generated correctly
+3. Delete `public/llms.txt` (optional—it's used as fallback)
+The middleware will automatically prefer the dynamic version.
+## Specification Compliance
+This implementation follows the official llms.txt specification:
+- ✅ H1 with project name (required)
+- ✅ Blockquote with summary (required)
+- ✅ Additional markdown sections (optional)
+- ✅ Proper content type (`text/plain`)
+- ✅ UTF-8 encoding
+## Resources
+- [llms.txt Official Site](https://llmstxt.org/)
+- [llms.txt Specification](https://llmstxt.org/spec)
+- [Example Sites](https://llmstxt.org/examples)
+## Support
+For questions or issues:
+- GitHub: [onto-sdk/issues](https://github.com/anthropics/onto-sdk/issues)
+- Docs: [buildonto.dev/docs](https://buildonto.dev/docs)