docs: Card-based Guides discovery page with category filtering#90
docs: Card-based Guides discovery page with category filtering#90rachaelrenk wants to merge 5 commits into
Conversation
- Extend content schema with tags and featured frontmatter fields - Backfill tags on all 54 guide pages using 15-tag vocabulary - Mark 6 guides as featured for the curated top section - Collapse all 7 sidebar groups by default to reduce overwhelm - Add GuidesLanding.astro component with card grid and filter pills - Replace static guides/index.mdx with dynamic filterable directory - Add CSS for cards, filter pills, category badges, and tag chips Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR replaces the Guides landing page with a generated card grid, category filters, featured guide metadata, and collapsed sidebar groups. The implementation is largely static build-time rendering with a small client-side filter script.
Concerns
- The filter controls are modeled as tabs even though they filter one card grid rather than switching between tab panels. This is non-blocking but should be adjusted for assistive technology semantics.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
|
||
| <div class="warp-guide-grid-container not-content"> | ||
| {/* Filter pills */} | ||
| <div class="warp-guide-filters" role="tablist" aria-label="Filter guides by category"> |
There was a problem hiding this comment.
💡 [SUGGESTION] These controls are filters, not tabs with associated tab panels; use a grouped button pattern with aria-pressed, or implement full tab keyboard and panel semantics.
topicSchema is a Zod object (not a function), so pass it directly to docsSchema.extend instead of wrapping in a typeof check. Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
changed the title
- Add text-decoration: none override on .warp-guide-card:hover and child elements to prevent Starlight's global link underline from cascading into card text - Rework Featured from a subsection of 'All' to its own filter pill (default active). 'All' now shows everything flat with no special section. Single card grid with data-featured attributes for JS filtering. Co-Authored-By: Oz <oz-agent@warp.dev>
1 participant
Summary
Replaces the flat link-list Guides landing page with a card-based discovery page inspired by OpenAI Cookbook and Modal examples. Adds category filter pills for instant client-side filtering, a curated "Featured" section, and collapses all sidebar groups to reduce visual overwhelm.
Context: The Guides section has 53+ pages across 7 categories, all listed flat in the sidebar. This made the section overwhelming and made it difficult for users to discover relevant guides. See the investigation plan for full research, reference site analysis, and design decisions.
Changes
Schema + metadata (Phase 1)
src/content.config.ts— ExtendeddocsSchemawithtags(array of strings) andfeatured(boolean) frontmatter fields, composed with existingtopicSchemasrc/sidebar.ts— Addedcollapsed: trueto all 7 Guides sidebar groups (Getting started, Agent workflows, Configuration, External tools, Build an app, DevOps, Frontend & UI).mdxfiles — Backfilled with tags from a 15-tag vocabulary (agents,mcp,rules,skills,profiles,code-review,docker,kubernetes,testing,database,cloud,frontend,getting-started,third-party-tools,build-app) and marked 6 guides asfeatured: trueCard-based discovery page (Phase 2)
src/components/GuidesLanding.astro— New component that queries thedocscollection at build time, renders a card grid with category badges and tag pills, and includes an inline<script>for client-side filter pill interactivitysrc/content/docs/guides/index.mdx— Replaced static link list with the<GuidesLanding />componentsrc/styles/custom.css— Added ~130 lines of CSS for filter pills, card grid, card styling, category badges, tag chips, and section headings (uses existing Warp brand tokens)Design decisions
starlight-tags(13 stars, single maintainer) but it only generates plain page lists, not card grids or client-side filteringNoMatchingRendererconflicts with thestarlight-llms-txtplugin during prerender; filtering is lightweight enough for vanilla JS/guides/landing page only, visually distinct from the site-wide header topic navHow to review
/guides/page — you should see filter pills at the top, a Featured section, then all guides as cardstags:in frontmatterWarp conversation
Co-Authored-By: Oz oz-agent@warp.dev