General Improvement Plan

[esthor]

How can we generally make this site better for users, discoverability/seo, and for "Agent Experience" ("AX")?

[esthor]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Establish SEO foundation by adding metadataBase, icons metadata, and canonical URLs to fix baseline metadata issues
• Implement JSON-LD structured data (Organization, Event, Person schemas) via reusable components to enable rich search results
• Fix UX gaps by utilizing existing but unused components (breadcrumbs) and surfacing already-fetched data (multi-speaker talks, dark-mode logos, event preview images)
• Create an llms.txt route following emerging conventions to make the site machine-readable for AI agents

Design Choices

Design Choice 1: JSON-LD Implementation Approach

Options Considered:

1. Inline <script type="application/ld+json"> via React components rendered in page bodies
2. Use Next.js metadata API's experimental jsonLd field (not yet stable)
3. Third-party library like next-seo or schema-dts

Chosen Option: 1

Rationale: Inline script components are the standard, stable approach used in Next.js apps and require no external dependencies.

Design Choice 2: Breadcrumb Scope

Options Considered:

1. Add breadcrumbs to PageLayout for site-wide consistency
2. Add breadcrumbs only to event detail pages where navigation depth matters

Chosen Option: 2

Rationale: Event detail pages are the primary use case where users navigate from homepage → event. Other pages are top-level and don't benefit from breadcrumbs.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: SEO & Metadata Foundation

Establish site-wide metadata best practices by fixing the root layout configuration. These changes affect every page and resolve known issues with OG image resolution and favicon handling.

Task 1: Add metadataBase and Icons to Root Layout

Configure the missing metadataBase so Next.js can resolve relative URLs in OG images and alternates. Wire up the existing favicon assets via the metadata API.

• Update app/src/app/layout.tsx to add metadataBase: new URL(mainConfig.instance.origin) to the metadata export
• Add icons object to metadata referencing the existing public assets: favicon.ico, favicon-16.png, favicon-32.png, apple-touch-icon.png, and the Android Chrome icons
• Remove manual origin prefixing from OG image URLs since metadataBase will handle resolution

Task 2: Add Canonical URLs to Key Pages

Add canonical URL metadata to prevent duplicate content issues and clarify the authoritative URL for each page.

• Update app/src/app/page.tsx metadata to include alternates: { canonical: "/" }
• Update app/src/app/about/page.tsx metadata to include canonical /about
• Update app/src/app/speakers/page.tsx generateMetadata() to include canonical /speakers
• Update app/src/app/[slug]/page.tsx generateMetadata() to include canonical /${slug}

🤖 Prompt for AI agents

Implement SEO & Metadata Foundation changes across the root layout and key page
files.

- In `app/src/app/layout.tsx`:
- Add `metadataBase: new URL(mainConfig.instance.origin)` to the exported
metadata object
- Add an `icons` object referencing existing public assets: `favicon.ico`,
`favicon-16.png`, `favicon-32.png`, `apple-touch-icon.png`, and the Android
Chrome icons
- Remove any manual origin prefixing from OG image URLs, since `metadataBase`
will now handle resolution
- Add `alternates: { canonical: "/" }` to the metadata export in
`app/src/app/page.tsx`
- Add `alternates: { canonical: "/about" }` to the metadata export in
`app/src/app/about/page.tsx`
- Update `generateMetadata()` in `app/src/app/speakers/page.tsx` to include
`alternates: { canonical: "/speakers" }`
- Update `generateMetadata()` in `app/src/app/[slug]/page.tsx` to include
`alternates: { canonical: "/${slug}" }` using the slug parameter

Phase 2: Structured Data (JSON-LD)

Implement JSON-LD structured data to enable rich search results. Event schema is particularly valuable for Google's event carousel, and Organization schema establishes site identity.

Task 1: Create JSON-LD Utility Component

Build a reusable component for rendering JSON-LD script tags safely.

• Create app/src/components/json-ld.tsx with a generic JsonLd component that accepts a typed schema object and renders it as <script type="application/ld+json">
• Use JSON.stringify with proper escaping for safe HTML embedding
• Export typed helper functions: organizationSchema(), eventSchema(), personSchema() that return properly structured objects

Task 2: Add Organization Schema to Root Layout

Establish the site's identity for search engines with Organization structured data.

• Add Organization JSON-LD to app/src/app/layout.tsx body (or a layout-level component)
• Include: name "All Things Web", URL, logo, social profile links (Discord, YouTube, Bluesky, Twitter, GitHub)
• Reference the existing social URLs from the about page

Task 3: Add Event Schema to Event Detail Pages

Enable rich event snippets in search results with Event structured data.

• Update app/src/app/[slug]/page.tsx to render Event JSON-LD with: name, description (tagline), startDate, endDate, location (address), image (preview image URL), organizer, and eventStatus
• Map isHackathon to appropriate @type (Hackathon events can use Event with additional context)
• Include the same schema in static event pages (2024-10-05-*, etc.) via shared component

Task 4: Add Person Schema to Speakers Page

Provide structured data for speaker profiles to improve discoverability.

• Update app/src/app/speakers/page.tsx to render an ItemList of Person schemas
• Each Person includes: name, jobTitle, image, sameAs (social profile URLs)
• Aggregate into a single JSON-LD block rather than per-speaker scripts

🤖 Prompt for AI agents

Implement JSON-LD structured data across the site using a reusable utility
component.

- Create `app/src/components/json-ld.tsx`:
- Implement a generic `JsonLd` component that accepts a typed schema object and
renders a `<script type="application/ld+json">` tag
  - Use `JSON.stringify` with proper escaping for safe HTML embedding
- Export typed helper functions: `organizationSchema()`, `eventSchema()`, and
`personSchema()` that return properly structured schema objects
- In `app/src/app/layout.tsx`:
- Add the `JsonLd` component to the layout body (or a layout-level component)
with an Organization schema
- Include: name "All Things Web", URL, logo, and social profile links (Discord,
YouTube, Bluesky, Twitter, GitHub) referencing existing social URLs from the
about page
- In `app/src/app/[slug]/page.tsx`:
- Render Event JSON-LD using the `JsonLd` component with fields: name,
description (tagline), startDate, endDate, location (address), image (preview
image URL), organizer, and eventStatus
  - Map `isHackathon` to the appropriate `@type`
- Apply the same schema to static event pages (e.g., `2024-10-05-*`) via the
shared component
- In `app/src/app/speakers/page.tsx`:
  - Render an ItemList of Person schemas using the `JsonLd` component
- Each Person entry includes: name, jobTitle, image, sameAs (social profile
URLs)
  - Aggregate all speakers into a single JSON-LD block

Phase 3: UX Improvements

Address content display gaps and navigation issues identified in the exploration. These fixes improve user experience by surfacing data that already exists but isn't rendered.

Task 1: Implement Breadcrumbs on Event Pages

Use the existing (unused) breadcrumb component to improve navigation context on event detail pages.

• Import breadcrumb components from app/src/components/ui/breadcrumb.tsx
• Add a breadcrumb trail to app/src/app/[slug]/page.tsx above the hero section: Home → Events → {Event Name}
• Style consistently with the page layout header
• Add corresponding BreadcrumbList JSON-LD schema alongside the Event schema

Task 2: Fix Multi-Speaker Talk Display

The TalksSection component only renders speakers[0], silently hiding additional speakers.

• Update app/src/components/event-details.tsx TalksSection to iterate over all speakers in the talk.speakers array
• Display multiple speaker avatars, names, and bios in a stacked or side-by-side layout within each talk card
• Ensure social links are shown for all speakers, not just the first

Task 3: Add Dark-Mode Sponsor Logo Support

Sponsor logos have both light and dark variants in the database, but only light is rendered.

• Update app/src/components/event-details.tsx SponsorsSection to conditionally render squareLogoLight or squareLogoDark based on current theme
• Use next-themes useTheme() hook or CSS prefers-color-scheme media query for switching
• Ensure the component handles cases where only one logo variant exists

Task 4: Show Event Preview Image in Hero Section

The hero currently displays a generic static PNG instead of the event's actual preview image.

• Update app/src/components/event-details.tsx HeroSection to use event.previewImage.url when available
• Fall back to the existing static placeholder images (/hero-image-hackathon.png, /hero-image-meetup.png) when no preview image is set
• Ensure proper image optimization with Next.js Image component and blur placeholder

Task 5: Fix RSS Link Target Behavior

On the about page, the RSS link opens in a new tab which is inappropriate for a feed URL.

• Update app/src/app/about/page.tsx RSS SocialBox to remove target="_blank" or set target="_self"
• RSS URLs should open in the same tab to allow the browser's native feed handling

🤖 Prompt for AI agents

Fix UX gaps in the site by utilizing existing but unused components and
surfacing already-fetched data.

- In `app/src/app/[slug]/page.tsx`:
  - Import breadcrumb components from `app/src/components/ui/breadcrumb.tsx`
- Add a breadcrumb trail above the hero section with the path: Home → Events →
{Event Name}
  - Style breadcrumbs consistently with the page layout header
  - Add a BreadcrumbList JSON-LD schema alongside the existing Event schema
- In `app/src/components/event-details.tsx`, `TalksSection`:
- Update to iterate over all entries in the `talk.speakers` array instead of
only rendering `speakers[0]`
- Display multiple speaker avatars, names, and bios in a stacked or side-by-side
layout within each talk card
  - Render social links for all speakers, not just the first
- In `app/src/components/event-details.tsx`, `SponsorsSection`:
- Conditionally render `squareLogoLight` or `squareLogoDark` based on the
current theme
- Use `next-themes` `useTheme()` hook or CSS `prefers-color-scheme` media query
for switching
  - Handle cases where only one logo variant exists
- In `app/src/components/event-details.tsx`, `HeroSection`:
  - Use `event.previewImage.url` when available instead of a generic static PNG
- Fall back to `/hero-image-hackathon.png` or `/hero-image-meetup.png` when no
preview image is set
- Ensure proper image optimization using the Next.js `Image` component with a
blur placeholder
- In `app/src/app/about/page.tsx`:
- Update the RSS `SocialBox` to remove `target="_blank"` or set `target="_self"`
so the RSS URL opens in the same tab

Phase 4: Agent Experience (AX)

Implement machine-readable content for AI agents, following the emerging llms.txt convention for LLM-friendly site documentation.

Task 1: Create llms.txt Route

Provide a plain-text summary of the site optimized for AI agent consumption.

• Create app/src/app/llms.txt/route.ts as a Next.js route handler returning text/plain
• Content should include: site purpose/description, key pages with brief descriptions, API endpoints overview, content structure explanation, and relevant context for agents trying to understand or interact with the site
• Structure the content with clear headers and concise descriptions (aim for ~500-1000 words)
• Consider generating some content dynamically (e.g., current event count, list of upcoming events)

Task 2: Reference llms.txt in Robots.txt

Make the llms.txt discoverable by adding a reference in the existing robots.txt handler.

• Update app/src/app/robots.txt/route.ts to include a comment or directive pointing to /llms.txt
• Follow emerging conventions (e.g., add a line like # AI agents: see /llms.txt for site documentation)

🤖 Prompt for AI agents

Implement machine-readable content for AI agents using the emerging `llms.txt`
convention.

- Create `app/src/app/llms.txt/route.ts` as a Next.js route handler:
  - Return a `text/plain` response
- Include content covering: site purpose/description, key pages with brief
descriptions, API endpoints overview, content structure explanation, and
relevant context for agents interacting with the site
- Structure content with clear headers and concise descriptions (~500-1000
words)
- Dynamically generate some content where appropriate (e.g., current event
count, list of upcoming events)
- Update `app/src/app/robots.txt/route.ts`:
- Add a comment or directive pointing to `/llms.txt` (e.g., `# AI agents: see
/llms.txt for site documentation`)
  - Follow emerging conventions for `llms.txt` discoverability

Research

All Things Web is a Next.js community event platform for Bay Area web developers. The app uses a standard App Router structure with pages at app/src/app/, components at app/src/components/, and data access via Drizzle ORM at app/src/lib/. The site has solid OG/Twitter metadata but lacks metadataBase, JSON-LD structured data, and machine-readable agent content. UI components follow shadcn/ui patterns. A breadcrumb component exists but is unused. Some fetched data (dark-mode logos, multi-speaker talks, event preview images) is not rendered in the UI.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement SEO & Metadata Foundation changes across the root layout and key page
files.

- In `app/src/app/layout.tsx`:
- Add `metadataBase: new URL(mainConfig.instance.origin)` to the exported
metadata object
- Add an `icons` object referencing existing public assets: `favicon.ico`,
`favicon-16.png`, `favicon-32.png`, `apple-touch-icon.png`, and the Android
Chrome icons
- Remove any manual origin prefixing from OG image URLs, since `metadataBase`
will now handle resolution
- Add `alternates: { canonical: "/" }` to the metadata export in
`app/src/app/page.tsx`
- Add `alternates: { canonical: "/about" }` to the metadata export in
`app/src/app/about/page.tsx`
- Update `generateMetadata()` in `app/src/app/speakers/page.tsx` to include
`alternates: { canonical: "/speakers" }`
- Update `generateMetadata()` in `app/src/app/[slug]/page.tsx` to include
`alternates: { canonical: "/${slug}" }` using the slug parameter
===============================================================================

Task: 2

Implement JSON-LD structured data across the site using a reusable utility
component.

- Create `app/src/components/json-ld.tsx`:
- Implement a generic `JsonLd` component that accepts a typed schema object and
renders a `<script type="application/ld+json">` tag
  - Use `JSON.stringify` with proper escaping for safe HTML embedding
- Export typed helper functions: `organizationSchema()`, `eventSchema()`, and
`personSchema()` that return properly structured schema objects
- In `app/src/app/layout.tsx`:
- Add the `JsonLd` component to the layout body (or a layout-level component)
with an Organization schema
- Include: name "All Things Web", URL, logo, and social profile links (Discord,
YouTube, Bluesky, Twitter, GitHub) referencing existing social URLs from the
about page
- In `app/src/app/[slug]/page.tsx`:
- Render Event JSON-LD using the `JsonLd` component with fields: name,
description (tagline), startDate, endDate, location (address), image (preview
image URL), organizer, and eventStatus
  - Map `isHackathon` to the appropriate `@type`
- Apply the same schema to static event pages (e.g., `2024-10-05-*`) via the
shared component
- In `app/src/app/speakers/page.tsx`:
  - Render an ItemList of Person schemas using the `JsonLd` component
- Each Person entry includes: name, jobTitle, image, sameAs (social profile
URLs)
  - Aggregate all speakers into a single JSON-LD block
===============================================================================

Task: 3

Fix UX gaps in the site by utilizing existing but unused components and
surfacing already-fetched data.

- In `app/src/app/[slug]/page.tsx`:
  - Import breadcrumb components from `app/src/components/ui/breadcrumb.tsx`
- Add a breadcrumb trail above the hero section with the path: Home → Events →
{Event Name}
  - Style breadcrumbs consistently with the page layout header
  - Add a BreadcrumbList JSON-LD schema alongside the existing Event schema
- In `app/src/components/event-details.tsx`, `TalksSection`:
- Update to iterate over all entries in the `talk.speakers` array instead of
only rendering `speakers[0]`
- Display multiple speaker avatars, names, and bios in a stacked or side-by-side
layout within each talk card
  - Render social links for all speakers, not just the first
- In `app/src/components/event-details.tsx`, `SponsorsSection`:
- Conditionally render `squareLogoLight` or `squareLogoDark` based on the
current theme
- Use `next-themes` `useTheme()` hook or CSS `prefers-color-scheme` media query
for switching
  - Handle cases where only one logo variant exists
- In `app/src/components/event-details.tsx`, `HeroSection`:
  - Use `event.previewImage.url` when available instead of a generic static PNG
- Fall back to `/hero-image-hackathon.png` or `/hero-image-meetup.png` when no
preview image is set
- Ensure proper image optimization using the Next.js `Image` component with a
blur placeholder
- In `app/src/app/about/page.tsx`:
- Update the RSS `SocialBox` to remove `target="_blank"` or set `target="_self"`
so the RSS URL opens in the same tab
===============================================================================

Task: 4

Implement machine-readable content for AI agents using the emerging `llms.txt`
convention.

- Create `app/src/app/llms.txt/route.ts` as a Next.js route handler:
  - Return a `text/plain` response
- Include content covering: site purpose/description, key pages with brief
descriptions, API endpoints overview, content structure explanation, and
relevant context for agents interacting with the site
- Structure content with clear headers and concise descriptions (~500-1000
words)
- Dynamically generate some content where appropriate (e.g., current event
count, list of upcoming events)
- Update `app/src/app/robots.txt/route.ts`:
- Add a comment or directive pointing to `/llms.txt` (e.g., `# AI agents: see
/llms.txt for site documentation`)
  - Follow emerging conventions for `llms.txt` discoverability

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!