Schema Markup & Structured Data Enhancements #230
Conversation
- Add TechArticle, Website, and BreadcrumbList schema markup to docs layout - Add FAQ schema to what-is-an-agent.mdx with common AI agent questions - Add HowTo schema to getting-started.mdx with step-by-step guide - Enhance meta descriptions with more context-rich content - Expand keywords to include AI agents and cloud deployment terms - Improve LLM understanding and discoverability per Vercel's recommendations Co-Authored-By: Rick Blalock <rickblalock@mac.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
WalkthroughThis update enhances SEO and discoverability by adding detailed JSON-LD structured data schemas to the layout and two documentation pages. The layout now injects TechArticle, WebSite, and BreadcrumbList schemas, while individual pages add FAQ and HowTo schemas. Metadata fields are also expanded for greater clarity and relevance. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant NextJS_App
participant SearchEngine
User->>NextJS_App: Request page (layout or content)
NextJS_App->>User: Serve HTML with metadata and JSON-LD scripts
User->>SearchEngine: Page is crawled
SearchEngine->>SearchEngine: Parse JSON-LD (TechArticle, WebSite, BreadcrumbList, FAQ, HowTo)
SearchEngine->>User: Enhanced search results (rich snippets, breadcrumbs, FAQs, etc.)
Possibly related PRs
Poem
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
npm error Exit handler never called! ✨ Finishing Touches
🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | 075cadc | Commit Preview URL | Jul 10 2025, 07:46 PM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
app/layout.tsx(4 hunks)content/Guides/what-is-an-agent.mdx(2 hunks)content/Introduction/getting-started.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
content/Introduction/getting-started.mdx (2)
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agentuity.mdc:0-0
Timestamp: 2025-07-01T12:36:39.469Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
content/Guides/what-is-an-agent.mdx (8)
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-01T12:36:46.237Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Use TypeScript for better type safety and IDE support
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agentuity.mdc:0-0
Timestamp: 2025-07-01T12:36:39.469Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : The file should export a default function
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-01T12:36:46.237Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Import types from `@agentuity/sdk`
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer loading types from the node modules package `@agentuity/sdk` in the node_modules folder
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Prefer using the `agentuity agent create` command to create a new Agent
Learnt from: afterrburn
PR: agentuity/docs#198
File: agent-docs/src/agents/doc-qa/index.ts:9-50
Timestamp: 2025-06-20T13:09:14.197Z
Learning: In the agent-docs codebase, the user prefers to let exceptions throw from Agent functions rather than adding local try-catch blocks, allowing errors to be handled at a higher level in the application.
app/layout.tsx (4)
Learnt from: afterrburn
PR: agentuity/docs#195
File: agent-docs/src/agents/doc-processing/docs-processor.ts:7-15
Timestamp: 2025-06-18T04:07:57.583Z
Learning: In the agent-docs project, the ChunkMetadata type requires title and description fields to be mandatory strings rather than optional, indicating that the system ensures these fields are always populated during document processing.
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-01T12:36:46.237Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Import types from `@agentuity/sdk`
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : The file should export a default function
🧬 Code Graph Analysis (1)
app/layout.tsx (1)
app/(docs)/layout.tsx (1)
Layout(8-27)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: docs
🔇 Additional comments (11)
content/Introduction/getting-started.mdx (2)
3-3: Enhanced description improves SEO clarity.The updated description effectively communicates the page's purpose and includes relevant keywords for better search visibility.
7-7: Script import correctly added for structured data.The Next.js Script component import is appropriate for adding JSON-LD structured data.
content/Guides/what-is-an-agent.mdx (3)
3-3: Enhanced description improves semantic clarity.The updated description effectively distinguishes between APIs and AI agents while highlighting the need for specialized cloud infrastructure.
6-6: Script import correctly added for structured data.The Next.js Script component import is appropriate for adding JSON-LD structured data.
8-61: Well-structured FAQ schema enhances SEO and user experience.The JSON-LD FAQ schema is excellently structured and provides valuable semantic information for search engines. The 5 questions cover key concepts about AI agents and can generate rich results in search. The answers are concise yet comprehensive, matching the page content well.
app/layout.tsx (6)
6-6: Script import correctly added for structured data.The Next.js Script component import is appropriate for adding JSON-LD structured data to the layout.
16-42: Enhanced metadata significantly improves SEO.The metadata improvements are excellent:
- More descriptive title and description
- Comprehensive keywords array covering relevant AI agent topics
- Better semantic clarity for search engines
67-91: OpenGraph and Twitter metadata enhancements improve social sharing.The updated social media metadata provides better descriptions and alt text for improved sharing experience.
97-97: Abstract field adds valuable semantic context.The abstract field provides a concise technical summary that helps with categorization and search understanding.
105-230: Approve JSON-LD schemas: All referenced URLs are reachableVerified that each URL in the TechArticle, WebSite, and BreadcrumbList scripts returns a 200/3xx status:
- https://www.agentuity.com
- https://www.agentuity.dev
- https://www.agentuity.dev/og-image.png
- https://www.agentuity.dev/search?q=test
Continue to monitor the size and render impact of these JSON-LD blocks in app/layout.tsx (lines 105–230); consider deferring non-critical schemas or server-side injection if you observe any performance regressions.
130-131: Verify publication and modification dates accuracyI wasn’t able to determine the actual creation or last-modified dates for
app/(docs)/layout.tsxvia Git history, so please confirm that the hardcoded values truly reflect your TechArticle’s real publication and most recent update:• File: app/(docs)/layout.tsx
Lines: 130–131- "datePublished": "2024-01-01", - "dateModified": "2024-12-01",Ensure these match your official records (CMS, blog metadata, commit logs, etc.).
| <Script | ||
| id="howto-schema" | ||
| type="application/ld+json" | ||
| strategy="afterInteractive" | ||
| > | ||
| {` | ||
| { | ||
| "@context": "https://schema.org", | ||
| "@type": "HowTo", | ||
| "name": "How to Get Started with Agentuity - Deploy AI Agents to the Cloud", | ||
| "description": "Complete step-by-step guide to get started with Agentuity, from creating an account to deploying your first AI agent to the cloud in minutes.", | ||
| "image": "https://www.agentuity.dev/og-image.png", | ||
| "totalTime": "PT10M", | ||
| "estimatedCost": { | ||
| "@type": "MonetaryAmount", | ||
| "currency": "USD", | ||
| "value": "0" | ||
| }, | ||
| "supply": [ | ||
| { | ||
| "@type": "HowToSupply", | ||
| "name": "Computer with internet connection" | ||
| }, | ||
| { | ||
| "@type": "HowToSupply", | ||
| "name": "Terminal or command line access" | ||
| } | ||
| ], | ||
| "tool": [ | ||
| { | ||
| "@type": "HowToTool", | ||
| "name": "Agentuity CLI", | ||
| "url": "https://agentuity.dev/CLI/installation" | ||
| } | ||
| ], | ||
| "step": [ | ||
| { | ||
| "@type": "HowToStep", | ||
| "position": 1, | ||
| "name": "Create a Free Account", | ||
| "text": "Create a free Agentuity account or sign in to the cloud portal. You can also signup using the CLI if you prefer.", | ||
| "url": "https://app.agentuity.com/sign-up", | ||
| "image": "https://www.agentuity.dev/og-image.png" | ||
| }, | ||
| { | ||
| "@type": "HowToStep", | ||
| "position": 2, | ||
| "name": "Install the CLI", | ||
| "text": "Install the Agentuity CLI, a cross-platform command-line tool for working with Agentuity Cloud. It supports Windows (using WSL), MacOS, and Linux.", | ||
| "url": "https://agentuity.dev/CLI/installation", | ||
| "image": "https://www.agentuity.dev/og-image.png" | ||
| }, | ||
| { | ||
| "@type": "HowToStep", | ||
| "position": 3, | ||
| "name": "Sign up for an Account with the CLI", | ||
| "text": "You can sign up for a free account using the CLI or skip this step if you already have an account.", | ||
| "url": "https://agentuity.dev/CLI/auth", | ||
| "image": "https://www.agentuity.dev/og-image.png" | ||
| }, | ||
| { | ||
| "@type": "HowToStep", | ||
| "position": 4, | ||
| "name": "Login to Agentuity", | ||
| "text": "You can skip this step if you used the CLI to sign up for an account, otherwise you must login to your account using the CLI.", | ||
| "url": "https://agentuity.dev/CLI/auth", | ||
| "image": "https://www.agentuity.dev/og-image.png" | ||
| }, | ||
| { | ||
| "@type": "HowToStep", | ||
| "position": 5, | ||
| "name": "Create Your First Project", | ||
| "text": "You can select a template to get started quickly with pre-built agent examples.", | ||
| "url": "https://agentuity.dev/CLI/project", | ||
| "image": "https://www.agentuity.dev/og-image.png" | ||
| }, | ||
| { | ||
| "@type": "HowToStep", | ||
| "position": 6, | ||
| "name": "Run Your Agent Locally", | ||
| "text": "You can run your agent locally to test it out before you deploy it to the cloud.", | ||
| "url": "https://agentuity.dev/CLI/dev", | ||
| "image": "https://www.agentuity.dev/og-image.png" | ||
| }, | ||
| { | ||
| "@type": "HowToStep", | ||
| "position": 7, | ||
| "name": "Deploy Your Project to the Cloud", | ||
| "text": "Deploy your agent to the cloud and start using it! The deployment process is automated and takes just a few minutes.", | ||
| "url": "https://agentuity.dev/CLI/cloud", | ||
| "image": "https://www.agentuity.dev/og-image.png" | ||
| } | ||
| ], | ||
| "about": [ | ||
| { | ||
| "@type": "Thing", | ||
| "name": "AI Agents", | ||
| "description": "Autonomous artificial intelligence systems" | ||
| }, | ||
| { | ||
| "@type": "Thing", | ||
| "name": "Cloud Deployment", | ||
| "description": "Deploying applications to cloud infrastructure" | ||
| } | ||
| ] | ||
| } | ||
| `} | ||
| </Script> |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Comprehensive HowTo schema enhances SEO but verify URLs and optimize performance.
The JSON-LD HowTo schema is well-structured and follows schema.org guidelines. It provides valuable semantic information for search engines and can generate rich results. However, there are a few considerations:
- URL Verification: Ensure all referenced URLs are valid and accessible
- Performance: This is a large JSON-LD block that could impact page load times
- Content Consistency: Verify the schema content matches the actual page content
🏁 Script executed:
#!/bin/bash
# Verify URLs referenced in the HowTo schema are accessible
urls=(
"https://app.agentuity.com/sign-up"
"https://agentuity.dev/CLI/installation"
"https://agentuity.dev/CLI/auth"
"https://agentuity.dev/CLI/project"
"https://agentuity.dev/CLI/dev"
"https://agentuity.dev/CLI/cloud"
"https://www.agentuity.dev/og-image.png"
)
for url in "${urls[@]}"; do
echo "Checking $url..."
curl -s -o /dev/null -w "%{http_code}" "$url" | grep -q "200\|301\|302" && echo "✓ $url is accessible" || echo "✗ $url may not be accessible"
doneLength of output: 2625
HowTo schema markup validated (all URLs accessible) but performance and content consistency need attention
- URLs ✓ All referenced links return HTTP 200–302.
- Performance ⚡ Consider minifying the JSON-LD payload, loading it asynchronously, or moving it to a static file to reduce render-blocking.
- Content Consistency 🔍 Manually verify that every step, name, URL, image, and metadata in the schema exactly matches the page’s visible content.
🤖 Prompt for AI Agents
In content/Introduction/getting-started.mdx between lines 9 and 116, the HowTo
schema JSON-LD is valid but can be optimized for performance and content
consistency. To fix this, minify the JSON-LD payload by removing unnecessary
whitespace and line breaks, load the script asynchronously or defer its loading
to avoid render-blocking, or move the JSON-LD data to a static file and
reference it. Additionally, manually verify that all step names, URLs, images,
and metadata exactly match the visible page content to ensure consistency.
|
Closing due to inactivity for more than 30 days. Configure here. |
Schema Markup & Structured Data Enhancements
Summary
This PR implements comprehensive LLM SEO optimizations following Vercel's recommendations for adapting SEO for AI search. The changes focus on adding structured data markup and enhancing metadata to improve how AI models understand and recommend Agentuity's content.
Key Changes:
Files Modified:
app/layout.tsx- Added TechArticle, Website, BreadcrumbList schemas + enhanced metadatacontent/Guides/what-is-an-agent.mdx- Added FAQ schema with 5 common AI agent questionscontent/Introduction/getting-started.mdx- Added HowTo schema with 7-step guideReview & Testing Checklist for Human
🔴 High Priority (3 items):
🟡 Medium Priority (2 items):
Diagram
%%{ init : { "theme" : "default" }}%% graph TB subgraph "Docs Repository" A["app/layout.tsx"]:::major-edit B["content/Guides/what-is-an-agent.mdx"]:::major-edit C["content/Introduction/getting-started.mdx"]:::major-edit end subgraph "Schema Types Added" D["TechArticle Schema"]:::context E["Website Schema"]:::context F["BreadcrumbList Schema"]:::context G["FAQ Schema"]:::context H["HowTo Schema"]:::context end A --> D A --> E A --> F B --> G C --> H subgraph Legend L1[Major Edit]:::major-edit L2[Minor Edit]:::minor-edit L3[Context/No Edit]:::context end classDef major-edit fill:#90EE90 classDef minor-edit fill:#87CEEB classDef context fill:#FFFFFFNotes
Summary by CodeRabbit
New Features
Documentation