Skip to content

Commit 440a95f

Browse files
claudeclaude
committed
Add comprehensive plan for showcase page implementation
This plan outlines a complete implementation strategy for a psake showcase page, similar to the Docusaurus showcase. It includes: - Data structure and TypeScript schema for showcase projects - Component architecture with 5 main components - Filtering, search, and favorites functionality - Build system integration with psake tasks and Pester tests - Submission workflow via GitHub discussions - 4-phase implementation plan (~1 week effort) - Future enhancement ideas The plan is structured to allow staged implementation following the phased approach outlined in the document.
1 parent 5a361f8 commit 440a95f

File tree

1 file changed

+340
-0
lines changed

1 file changed

+340
-0
lines changed

‎SHOWCASE_PLAN.md‎

Lines changed: 340 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,340 @@
1+
# Plan: psake Showcase Page Implementation
2+
3+
## Overview
4+
Create a showcase page to highlight projects and organizations using psake for build automation, similar to the [Docusaurus showcase](https://docusaurus.io/showcase).
5+
6+
## 1. Data Structure & Schema
7+
8+
### Create Data File: `src/data/showcase.tsx`
9+
10+
Define TypeScript types and data structure:
11+
12+
```typescript
13+
export type TagType =
14+
| 'favorite' // Curated favorites by psake team
15+
| 'opensource' // Open-source projects
16+
| 'commercial' // Commercial/enterprise projects
17+
| 'cicd' // CI/CD integration examples
18+
| 'dotnet' // .NET projects
19+
| 'module' // PowerShell module builds
20+
| 'large' // Large projects (>100 tasks)
21+
| 'testing' // Strong test automation
22+
23+
export type ShowcaseProject = {
24+
title: string; // Project name
25+
description: string; // Max 120 characters
26+
preview: string; // Path to screenshot (640px min width)
27+
website: string | null; // Project website/docs
28+
source: string; // GitHub/GitLab repository
29+
tags: TagType[]; // Category tags
30+
};
31+
32+
export const projects: ShowcaseProject[] = [
33+
// Initial seed projects
34+
];
35+
```
36+
37+
### Image Storage Structure
38+
- Create directory: `static/img/showcase/`
39+
- Naming convention: `{project-slug}.png` or `.jpg`
40+
- Requirements: Min 640px width, max 2:1 aspect ratio
41+
- Optimize images before adding (use build task)
42+
43+
## 2. Component Architecture
44+
45+
### 2.1 Main Page Component
46+
**File:** `src/pages/showcase/index.tsx`
47+
48+
```typescript
49+
export default function Showcase(): JSX.Element {
50+
return (
51+
<Layout title="Showcase" description="Projects built with psake">
52+
<ShowcaseHeader />
53+
<main className="margin-vert--lg">
54+
<ShowcaseFilters />
55+
<ShowcaseSearchBar />
56+
<ShowcaseCards />
57+
</main>
58+
</Layout>
59+
);
60+
}
61+
```
62+
63+
### 2.2 Sub-Components
64+
65+
**File:** `src/components/showcase/ShowcaseHeader.tsx`
66+
- Title: "psake Showcase"
67+
- Subtitle: "Discover projects built with psake"
68+
- CTA button: "Submit Your Project" (links to GitHub discussion)
69+
70+
**File:** `src/components/showcase/ShowcaseFilters.tsx`
71+
- Tag-based filtering (multi-select)
72+
- AND/OR toggle for filter logic
73+
- "Clear All" button
74+
- Active filter count display
75+
76+
**File:** `src/components/showcase/ShowcaseSearchBar.tsx`
77+
- Real-time search across title + description
78+
- Fuzzy matching support
79+
- Search result count
80+
81+
**File:** `src/components/showcase/ShowcaseCard.tsx`
82+
- Project screenshot with hover effect
83+
- Title (links to website or source)
84+
- Description
85+
- Tag badges
86+
- GitHub link icon
87+
- Website link icon (if available)
88+
89+
**File:** `src/components/showcase/ShowcaseCards.tsx`
90+
- Grid layout (responsive: 1/2/3 columns)
91+
- "Favorites" section first (if any favorites exist)
92+
- "All Projects" section (alphabetically sorted)
93+
- Empty state when no results
94+
95+
### 2.3 Styling
96+
**File:** `src/components/showcase/styles.module.css`
97+
- Card hover effects
98+
- Tag badge colors
99+
- Responsive grid layout
100+
- Filter button styles
101+
- Search input styling
102+
103+
## 3. Key Features Implementation
104+
105+
### 3.1 Filtering System
106+
- Multi-tag selection (OR logic by default)
107+
- Toggle between AND/OR filtering
108+
- Persist filter state in URL query params
109+
- Filter count badge
110+
111+
### 3.2 Search Functionality
112+
- Case-insensitive search
113+
- Search across: title, description, tags
114+
- Real-time results update
115+
- Combine with filters (AND logic)
116+
117+
### 3.3 Favorites Section
118+
- Manually curated by psake maintainers
119+
- Display prominently at top
120+
- Larger card size option
121+
- "Featured" badge/ribbon
122+
123+
### 3.4 Responsive Design
124+
- Mobile: 1 column
125+
- Tablet: 2 columns
126+
- Desktop: 3 columns
127+
- Touch-friendly filter buttons
128+
129+
## 4. Integration with Existing Site
130+
131+
### 4.1 Navigation Updates
132+
**File:** `docusaurus.config.ts`
133+
134+
Add to navbar items (line 89):
135+
```typescript
136+
{ to: '/showcase', label: 'Showcase', position: 'left' },
137+
```
138+
139+
### 4.2 Footer Updates
140+
Add to "Community" section (line 141):
141+
```typescript
142+
{
143+
label: 'Showcase',
144+
to: '/showcase',
145+
},
146+
```
147+
148+
### 4.3 Homepage Link
149+
**File:** `src/pages/index.tsx`
150+
151+
Add CTA button or section linking to showcase
152+
153+
## 5. Submission Workflow
154+
155+
### 5.1 GitHub Discussion Setup
156+
- Create GitHub Discussion category: "Showcase Submissions"
157+
- Template for submissions:
158+
```markdown
159+
**Project Name:**
160+
**Description:** (max 120 chars)
161+
**Website:** (optional)
162+
**Source Repository:**
163+
**Screenshot URL:** (upload to discussion)
164+
**Suggested Tags:**
165+
```
166+
167+
### 5.2 Review Process
168+
1. User submits via GitHub discussion
169+
2. Maintainer reviews:
170+
- Validates project uses psake
171+
- Checks screenshot quality (640px min, 2:1 ratio)
172+
- Verifies links work
173+
- Optimizes image
174+
3. Maintainer creates PR:
175+
- Adds entry to `src/data/showcase.tsx`
176+
- Adds optimized image to `static/img/showcase/`
177+
- Updates relevant tags
178+
179+
### 5.3 Image Optimization Task
180+
**File:** `psakeFile.ps1`
181+
182+
Add new task:
183+
```powershell
184+
Task OptimizeShowcaseImages {
185+
# Use ImageMagick or similar to:
186+
# - Resize to max 1280px width
187+
# - Compress to <200KB
188+
# - Convert to WebP format (with fallback)
189+
}
190+
```
191+
192+
## 6. Build System Integration
193+
194+
### 6.1 Validation Task
195+
**File:** `psakeFile.ps1`
196+
197+
```powershell
198+
Task ValidateShowcase {
199+
# Check all images exist
200+
# Validate image dimensions
201+
# Ensure descriptions <= 120 chars
202+
# Verify all URLs are reachable
203+
}
204+
```
205+
206+
Add to `Test` task dependencies
207+
208+
### 6.2 Pester Tests
209+
**File:** `tests/Showcase.Tests.ps1`
210+
211+
```powershell
212+
Describe 'Showcase Data Validation' {
213+
It 'All projects have valid images' { }
214+
It 'All descriptions are <= 120 characters' { }
215+
It 'All source URLs are valid GitHub/GitLab links' { }
216+
It 'No duplicate project titles' { }
217+
It 'All tags are valid TagType values' { }
218+
}
219+
```
220+
221+
## 7. Content Strategy
222+
223+
### 7.1 Initial Seed Projects
224+
Reach out to known psake users:
225+
- psake itself (meta)
226+
- Popular PowerShell modules using psake
227+
- .NET projects with psake builds
228+
- CI/CD pipeline examples
229+
230+
Target: 10-15 initial projects before launch
231+
232+
### 7.2 Tag Categories
233+
- **favorite**: Maintainer-curated highlights (3-5 max)
234+
- **opensource**: Public repositories
235+
- **commercial**: Enterprise/product builds
236+
- **cicd**: CI/CD integration showcases
237+
- **dotnet**: .NET project builds
238+
- **module**: PowerShell module automation
239+
- **large**: Complex builds (>100 tasks)
240+
- **testing**: Test automation examples
241+
242+
## 8. SEO & Metadata
243+
244+
### Page Metadata
245+
```typescript
246+
<Layout
247+
title="Showcase - Projects Built with psake"
248+
description="Discover real-world projects using psake for build automation in PowerShell, .NET, and CI/CD pipelines."
249+
>
250+
```
251+
252+
### Social Card
253+
Create custom social card: `static/img/showcase-social-card.png`
254+
255+
## 9. Implementation Phases
256+
257+
### Phase 1: Core Structure (Day 1-2)
258+
- [ ] Create data schema and initial file
259+
- [ ] Build main page component
260+
- [ ] Implement basic card grid
261+
- [ ] Add to navigation
262+
263+
### Phase 2: Filtering & Search (Day 3-4)
264+
- [ ] Implement tag filtering
265+
- [ ] Add search functionality
266+
- [ ] URL query param persistence
267+
- [ ] Mobile responsive design
268+
269+
### Phase 3: Polish & Integration (Day 5)
270+
- [ ] Favorites section
271+
- [ ] Styling and animations
272+
- [ ] Empty states
273+
- [ ] Build system integration
274+
275+
### Phase 4: Validation & Launch (Day 6-7)
276+
- [ ] Pester tests
277+
- [ ] Documentation
278+
- [ ] Seed initial projects
279+
- [ ] GitHub discussion setup
280+
- [ ] Deploy and announce
281+
282+
## 10. Future Enhancements
283+
284+
### Post-Launch Improvements
285+
- **Community voting**: Let users upvote favorites
286+
- **Sorting options**: By date added, popularity, name
287+
- **Project stats**: Task count, lines of code, contributors
288+
- **Category pages**: Dedicated pages per tag
289+
- **RSS feed**: New showcase additions
290+
- **Automated screenshots**: GitHub Action to capture screenshots
291+
- **Rich previews**: Embed GitHub stats (stars, forks)
292+
293+
### Advanced Features
294+
- **Web form submission**: Direct submission without GitHub account
295+
- **Automated validation**: GitHub Action to validate PRs
296+
- **Featured rotation**: Rotate featured projects monthly
297+
- **Case studies**: Detailed write-ups for select projects
298+
299+
## 11. Success Metrics
300+
301+
Track after 3 months:
302+
- Number of showcase projects (Target: 30+)
303+
- Submission rate (Target: 2-3/month)
304+
- Showcase page views
305+
- Click-through to project repos
306+
- Community engagement in discussions
307+
308+
---
309+
310+
## Dependencies
311+
312+
**NPM Packages** (already available):
313+
- ✅ `clsx` - Conditional classnames
314+
- ✅ `react` & `react-dom` - React framework
315+
- ✅ TypeScript - Type safety
316+
317+
**No additional dependencies required!**
318+
319+
## Estimated Effort
320+
321+
- **Development**: 3-5 days
322+
- **Testing & Polish**: 1-2 days
323+
- **Seed Content**: 2-3 days (parallel)
324+
- **Total**: ~1 week for MVP launch
325+
326+
## References & Sources
327+
328+
- [Docusaurus Site Showcase](https://docusaurus.io/showcase)
329+
- [Docusaurus showcase/index.tsx](https://github.com/facebook/docusaurus/blob/main/website/src/pages/showcase/index.tsx)
330+
- [Docusaurus showcase data structure](https://github.com/facebook/docusaurus/blob/main/website/src/data/users.tsx)
331+
- [Showcase submissions discussion](https://github.com/facebook/docusaurus/discussions/7826)
332+
- [Showcase infrastructure issue](https://github.com/facebook/docusaurus/issues/6882)
333+
334+
---
335+
336+
## Notes
337+
338+
This plan provides a complete roadmap for implementing a professional, scalable showcase page that will help grow the psake community by highlighting real-world usage and success stories.
339+
340+
The implementation can be done in stages following the phases outlined in Section 9, allowing for incremental development and testing.

0 commit comments

Comments
 (0)