docs: Card-based Guides discovery page with category filtering#90
Open
rachaelrenk wants to merge 11 commits into
Open
docs: Card-based Guides discovery page with category filtering#90rachaelrenk wants to merge 11 commits into
rachaelrenk wants to merge 11 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.
|
Contributor
|
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}
Contributor
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"> |
Contributor
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>
- Reduce grid min-width from 280px to 220px (fits 3 cols in ~730px content area) - Reduce card padding from 1.25rem to 0.875rem vertical / 1rem horizontal - Reduce internal card gap from 0.5rem to 0.25rem - Reduce grid gap from 1rem to 0.75rem - Shrink title from text-body to text-sm - Shrink description from text-sm to text-2xs, clamp to 2 lines - Add tighter line-height on category eyebrow Co-Authored-By: Oz <oz-agent@warp.dev>
Swap editorially-chosen featured guides for traffic-validated picks: New featured (6): - Set up Claude Code (3.7K views) - Set up Ollama (2.1K views) - 10 coding features you should know (721 views) - Run multiple AI coding agents (636 views) - Review AI-generated code (410 views) - Using MCP servers with Warp (187 views, integrations gateway) Removed: - Explain your codebase (low traffic) - Run 3 agents in parallel (low traffic) - Create project rules (low traffic) - Sentry MCP (low traffic) - Build a real-time chat app (low traffic) Co-Authored-By: Oz <oz-agent@warp.dev>
Replace directory-based categories (Getting started, Agent workflows, Configuration, etc.) with problem/solution use-case categories that cut across the filesystem structure: - Set up your environment (9) — first steps + tool installation - Work with agents (10) — prompting, voice, images, parallel tasks - Automate your workflow (10) — rules, profiles, prompts, skills - Connect external services (9) — MCP servers - Build & deploy apps (9) — app builds, Docker, K8s, cloud, frontend - Review & debug (7) — PR review, code review, testing, database, secrets Each guide is mapped to exactly one category via GUIDE_CATEGORIES in GuidesLanding.astro. New guides need a single entry added to this map. Co-Authored-By: Oz <oz-agent@warp.dev>
Standardize all 54 guide page titles and sidebar labels per the docs style guide (sentence case, proper feature names preserved): - 'How To:' / 'How to:' / 'How To' → 'How to' (no colon, consistent) - Title Case words → lowercase (except product names) - Preserved: Warp, Claude Code, Codex CLI, Gemini CLI, OpenCode, Ollama, MCP, Docker, Kubernetes, SQL, Postgres, REPL, GitHub, Linear, Sentry, Figma, Chrome, Slackbot, Rules, Skills, Agent Profiles, Code Review, Cloud Run, YOLO, Astro, React, Tailwind, Rust, D3.js, JavaScript, HTML, CSS, Railway - Fixed 'Javascript' → 'JavaScript' in Chrome extension title - Updated both frontmatter titles and sidebar.ts labels Co-Authored-By: Oz <oz-agent@warp.dev>
All guide titles now use imperative verbs consistently: - 'How to set up Claude Code' → 'Set up Claude Code' - 'Building a Slackbot' → 'Build a Slackbot' - 'Understanding your codebase' → 'Understand your codebase' - 'Using MCP servers with Warp' → 'Use MCP servers with Warp' 40 titles updated. Titles that don't follow a verb pattern are unchanged (numbered lists, comparisons, MCP colon format). Co-Authored-By: Oz <oz-agent@warp.dev>
- Accept main's new title for using-mcp-servers-with-warp (rewritten page) - Accept main's deletion of building-a-slackbot guide - Add 2 new guides from main to sidebar (sentence case) and GUIDE_CATEGORIES: - attach-agent-session-context-to-github-prs → agents - run-unattended-agents → agents - Keep our card grid landing page (GuidesLanding component) - Keep our sentence-case formatting for all sidebar labels Co-Authored-By: Oz <oz-agent@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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