feat: Redesign automation examples as card-based marketplace linked to use cases#454
Open
feat: Redesign automation examples as card-based marketplace linked to use cases#454
Conversation
…o use cases - Redesign automation examples page with card-based UI organized into 'Use Case Automations' and 'General Automations' sections - Each use-case automation card links to the full guide, relevant plugin, and includes a copyable prompt with Prompt/Plugin tabs - General automations displayed as a 3-column card grid for discoverability - Tips section collapsed into AccordionGroup to reduce visual noise - Add 'Automate This' sections to 4 use case pages (vulnerability remediation, code review, incident triage, dependency upgrades) with ready-to-use automation prompts and link to the examples page - Update use-cases overview with new 'Automate Any Use Case' section showing cards for Automation Templates, Plugins, and SDK - Cross-link use cases ↔ automations ↔ plugins bidirectionally Co-authored-by: openhands <openhands@all-hands.dev>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…L data
- Add _data/use-case-automations.yaml as single source of truth for
use-case → automation mappings (title, icon, prompt, plugin link, etc.)
- Add .github/scripts/sync_use_case_automations.py to generate/validate
the auto-generated MDX sections between marker comments
- Add .github/workflows/sync-use-case-automations.yml CI check that
runs on PRs touching the data file, examples page, or use-case pages
- Add {/* BEGIN/END */} marker comments to examples.mdx and 4 use-case
pages so the script knows which sections to regenerate
Workflow:
1. Edit _data/use-case-automations.yaml (add/modify use cases)
2. Run: python .github/scripts/sync_use_case_automations.py
3. Commit the YAML + regenerated MDX files
4. CI validates everything stays in sync
Co-authored-by: openhands <openhands@all-hands.dev>
… file The automation content for each use case is now defined in the use-case page's own frontmatter (automation: block). The sync script reads those pages directly — no separate _data/ file to maintain. - Remove _data/use-case-automations.yaml - Add automation: frontmatter to 4 use-case pages (vulnerability- remediation, code-review, incident-triage, dependency-upgrades) - Rewrite sync script to parse MDX frontmatter and generate the examples page cards + Automate This sections from it - Simplify workflow triggers (no more YAML data path) Adding a new use-case automation: 1. Add automation: block to the use-case page's frontmatter 2. Add BEGIN/END:automate-this markers where the section should go 3. Run: python .github/scripts/sync_use_case_automations.py 4. Commit the updated files — CI validates on every PR Co-authored-by: openhands <openhands@all-hands.dev>
The Automate This sections were duplicating the prompt already defined in frontmatter. Now use-case pages just have a simple card linking back to the automation examples page (with an anchor to the specific use case). The prompt content lives in one place only — the frontmatter — and the sync script copies it to examples.mdx. - Remove generated Automate This blocks and markers from use-case pages - Replace with a static Card linking to examples page anchor - Remove unused intro field from frontmatter - Simplify sync script to only generate the examples page Co-authored-by: openhands <openhands@all-hands.dev>
… a card index Use-case pages are now the single source of truth: - Frontmatter has only card metadata (title, icon, short description) - Page body has the full 'Automate This' section with prompts, context, and plugin links — this is what users actually read and copy The automation examples page is just a card grid that links to each use-case page's #automate-this section. The sync script generates those cards from the frontmatter metadata. Co-authored-by: openhands <openhands@all-hands.dev>
Each prompt now ends with 'Learn more at <url>' pointing back to the use-case documentation page, so users (and agents) always have context on where the prompt came from. Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
requested changes
Apr 14, 2026
Contributor
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
The core idea is solid—using use-case frontmatter as the source of truth for automation cards is the right approach. But the implementation is incomplete and doesn't match what the PR description promises. See inline comments for specifics.
Review fixes: - Remove card_title duplication — use page title instead - Rename card_description to summary (simpler frontmatter) - Add field validation with clear error messages for missing fields - Add marker validation (fail loudly on missing/misordered markers) - Add 13 tests covering parsing, generation, and error cases Page merge: - Merge automations/examples.mdx into automations/overview.mdx (single page with overview + use-case cards + general templates) - Delete the separate examples page - Update docs.json navigation - Fix all internal links across the site Co-authored-by: openhands <openhands@all-hands.dev>
Contributor
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Taste Rating: 🟡 Acceptable - Solid implementation with comprehensive tests, but the error handling logic is more convoluted than necessary.
Verdict: ✅ Worth merging - Core logic is sound, test coverage is excellent, minor improvement suggested.
Key Insight: The sync script correctly validates frontmatter and generates cards, but the error collection pattern forces you to think harder than you should about whether data gets appended when other files have errors.
- Replace confusing 'all(f" {rel}" not in e ...)' with simple
'file_has_errors' boolean flag per reviewer suggestion
- Add redirect from /automations/examples to /automations/overview
so external links don't 404
Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
approved these changes
Apr 14, 2026
Contributor
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Taste Rating: 🟡 Acceptable - Solid, pragmatic implementation.
Verdict: ✅ Worth merging - Clean data flow, comprehensive tests, addresses real problem.
Key Insight: Using frontmatter as the single source of truth with automated sync eliminates the manual drift problem elegantly—this is good engineering that solves a real maintenance pain point.
What's Right:
- Data structure: Frontmatter-as-source-of-truth is the correct choice—one authoritative location, no duplication
- Testing: 13 tests covering all error paths and happy cases; tests verify real behavior, not mocks
- Backward compatibility: Redirect in place prevents breaking external links
- Error handling: Clean validation with clear messages (fixed from previous review)
- No complexity sins: Simple functions, no deep nesting, single responsibilities
Minor Suggestion (non-blocking):
PR description could include visual evidence—e.g., a screenshot of the rendered card grid or command output showing the sync script running successfully. The test coverage makes this acceptable without it, but future PRs with UI changes benefit from visual proof.
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
3 participants
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
Adds a card-based "Use Case Automations" section to the automations overview page, auto-generated from use-case frontmatter.
Architecture
Use-case pages are the single source of truth:
automation:frontmatter (icon,summary) — card title comes from the pagetitle(no duplication)Automations overview page (merged with examples):
#automate-thissectionSync script (
.github/scripts/sync_use_case_automations.py):automation:frontmatter from use-case pagesoverview.mdxbetween marker comments.github/workflows/sync-use-case-automations.ymlChanges
automations/examples.mdxintoautomations/overview.mdx(single page)automations/examples.mdxdocs.jsonnavigation (removed examples entry)card_title(uses pagetitle), renamedcard_description→summaryThis PR was created by an AI assistant (OpenHands) on behalf of Xingyao.