Restructure docs IA and improve SEO fundamentals#653
Restructure docs IA and improve SEO fundamentals#653ryanycoleman wants to merge 6 commits intostrands-agents:mainfrom
Conversation
Nav tabs reduced from 9 to 5: merged Labs and Contribute into Community, merged Python API and TypeScript API into a single API Reference tab with a sidebar language switcher, renamed User Guide to Docs. Blog tab will be added by a separate PR. Sidebar reorganized with a new task-first "Build" section (Adding Tools, Using MCP Tools, Multi-Agent Systems, Streaming Responses, Voice & Realtime, etc.) positioned above Concepts. Deploy promoted from last to after Model Providers. Homepage CTA now links directly to the Python quickstart, skipping the overview routing page. New "Why Strands?" page with model-driven vs workflow-driven comparison, code examples, and a Python/TypeScript feature matrix. Initial draft — content needs refinement. Sidebar labels now sourced from navigation.yml rather than page frontmatter, so nav labels can differ from page titles without touching individual content files.
The XML sitemap previously had bare <loc> entries with no freshness signal. Search engines and AI crawlers use <lastmod> to prioritize recently updated content — without it, all pages appear equally stale. This adds a small Astro integration that runs a single git log command at build time to collect the last commit date for each content file, then injects those dates into the sitemap via the @astrojs/sitemap serialize callback. Generated API reference pages are skipped since they aren't git-tracked. Result: 143 of 401 sitemap URLs now include <lastmod> dates. The remainder are auto-generated API docs whose freshness is better signaled by SDK version numbers.
… tags - Optimize homepage title and meta description for search intent - Add unique meta descriptions to top 20 documentation pages - Add JSON-LD structured data (Organization, SoftwareApplication, BreadcrumbList) to all pages - Add Open Graph image and Twitter card tags site-wide - Create branded OG social preview image (1200x630) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ryanycoleman
temporarily deployed
to
auto-approve
GitHub Actions
Inactive
ryanycoleman
had a problem deploying
to
auto-approve
GitHub Actions
Failure
Documentation Preview FailedThe documentation deployment encountered an error. Please check the deployment logs for more details. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
src/plugins/sitemap-lastmod.ts
Outdated
| map.set(trimmed, currentDate) | ||
| } | ||
| } | ||
| } catch { |
There was a problem hiding this comment.
Issue: Bare catch block may hide unexpected errors
The empty catch block will silently swallow any error, not just "git not available". For example, if the buffer is too small or there's a permission issue, these would be hidden.
Suggestion: Consider catching specific error types or at least logging the actual error:
} catch (error) {
console.warn('[sitemap-lastmod] Failed to build lastmod map:', error instanceof Error ? error.message : error)
}There was a problem hiding this comment.
✅ Addressed - now logs the actual error message for debugging.
src/components/overrides/Head.astro
Outdated
| const faviconHref = base.endsWith('/') ? `${base}favicon.svg` : `${base}/favicon.svg` | ||
|
|
||
| // Build breadcrumb list from URL path | ||
| const siteUrl = 'https://strandsagents.com' |
There was a problem hiding this comment.
Issue: Hardcoded site URL duplicates configuration
The siteUrl is hardcoded here, but Astro already has this configured via Astro.site (which is set in astro.config.mjs).
Suggestion: Use Astro.site?.origin || 'https://strandsagents.com' for consistency with the rest of the codebase and to avoid drift if the domain changes.
There was a problem hiding this comment.
✅ Addressed - now using Astro.site?.origin || 'https://strandsagents.com'
| <meta name="twitter:image" content={new URL('/og-image.png', Astro.site).href} /> | ||
|
|
||
| <!-- Structured Data --> | ||
| <script type="application/ld+json" set:html={JSON.stringify({ |
There was a problem hiding this comment.
Issue: JSON-LD structured data is duplicated
The Organization and SoftwareApplication schemas here are nearly identical to those in Head.astro. This duplication makes maintenance harder and risks inconsistencies.
Suggestion: Extract the shared structured data (Organization, SoftwareApplication) to a utility function or shared constant that both files can import. The landing page could then just add the WebSite/SearchAction schema that's unique to it.
There was a problem hiding this comment.
✅ Addressed - created src/util/structured-data.ts with shared baseSchemas() function. Nice clean solution!
There was a problem hiding this comment.
Assessment: Comment
Solid improvements to IA and SEO. The navigation consolidation is sensible and the structured data implementation follows best practices.
Review Categories
- Code Quality: A few opportunities to reduce duplication (JSON-LD schemas) and improve error handling (sitemap plugin)
- SEO Implementation: Well-structured meta tags and JSON-LD schemas that should improve search visibility
- Architecture: The
additionalBasePathspattern for nav consolidation is clean and maintainable
The new API language switcher in the sidebar is a nice UX improvement. All tests pass. 🎉
- Log actual error in sitemap-lastmod catch block - Extract shared JSON-LD schemas to src/util/structured-data.ts - Use Astro.site?.origin instead of hardcoded site URL in Head.astro
ryanycoleman
had a problem deploying
to
auto-approve
GitHub Actions
Failure
ryanycoleman
temporarily deployed
to
auto-approve
GitHub Actions
Inactive
Documentation Preview FailedThe documentation deployment encountered an error. Please check the deployment logs for more details. |
ryanycoleman
temporarily deployed
to
auto-approve
GitHub Actions
Inactive
ryanycoleman
had a problem deploying
to
auto-approve
GitHub Actions
Failure
Documentation Preview FailedThe documentation deployment encountered an error. Please check the deployment logs for more details. |
ryanycoleman
had a problem deploying
to
auto-approve
GitHub Actions
Failure
Documentation Preview FailedThe documentation deployment encountered an error. Please check the deployment logs for more details. |
1 participant
Description
better discoverability. Reorder "Get Started" and "Build" sections to lead with tasks.
Test plan
Checklist
npm run devBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.