Skip to content

Commit 55432d5

Browse files
pedrofuentespedrofuentes
committed
feat: add Elgato Marketplace content folder with assets, descriptions, and tooling
- Add content/CONTENT-GUIDE.md with agent instructions for marketplace maintenance - Add content/description.md plugin description (~2,850 / 4,000 chars) - Add content/release-notes.md for all versions (v1.0.0 through v2.3.0) - Add content/marketplace-content.html copy-paste ready HTML with tabbed release notes - Add 6 SVG source assets (icon, thumbnail, 4 gallery images) with generated PNGs - Add scripts/convert-content-assets.ts SVG-to-PNG converter using @resvg/resvg-js - Add npm script: content:assets - Update AGENTS.md and copilot-instructions.md with content/ references and post-release steps
1 parent 0364fea commit 55432d5

20 files changed

+2625
-41
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,8 @@ const flashEnabled = settings.flashOnMeetingStart === true;
314314
- **PI HTML**: `pi/setup.html` - Settings popup (Named Calendars management)
315315
- **PI JS**: `pi/setup.js` - Settings logic (not TypeScript)
316316
- **Tests**: `tests/` - Vitest test files
317+
- **Marketplace Content**: `content/` - Description, release notes, assets (see `content/CONTENT-GUIDE.md`)
318+
- **Asset Converter**: `scripts/convert-content-assets.ts` - SVG → PNG for marketplace assets
317319

318320
## Release Process
319321

@@ -467,6 +469,21 @@ git push origin --delete feature/vX.Y.Z-branch-name
467469
streamdeck link "dist/com.pedrofuentes.ical.sdPlugin"
468470
```
469471

472+
#### 10. Update Elgato Marketplace Content
473+
474+
After every release, update the marketplace listing:
475+
476+
1. Write release notes in `content/release-notes.md`
477+
2. Review `content/description.md` — update if features changed
478+
3. Update `content/marketplace-content.html` with matching HTML
479+
4. Update gallery SVGs in `content/assets/` if key display changed
480+
5. Run `npm run content:assets` to regenerate PNGs
481+
6. Commit content changes with the version bump
482+
7. After GitHub Release: open HTML file in browser, copy, paste into Elgato Marketplace WYSIWYG
483+
8. After GitHub Release: upload new asset PNGs if changed
484+
485+
See `content/CONTENT-GUIDE.md` for full details.
486+
470487
### Quick Reference Commands
471488

472489
```powershell

‎AGENTS.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ This is a Stream Deck plugin that displays iCal calendar events. See `.github/co
1616
| `src/services/recurrence-expander.ts` | RRULE expansion and RECURRENCE-ID handling |
1717
| `tests/` | Vitest test files |
1818
| `__fixtures__/` | Test fixtures organized by provider |
19+
| `content/` | Elgato Marketplace listing content (description, release notes, assets) |
20+
| `content/CONTENT-GUIDE.md` | Agent instructions for marketplace content maintenance |
21+
| `scripts/convert-content-assets.ts` | SVG → PNG converter for marketplace assets |
1922

2023
## Testing Requirements
2124

@@ -26,6 +29,15 @@ Every code change MUST include corresponding tests:
2629

2730
Always run `npm test` before completing work.
2831

32+
## Useful Commands
33+
34+
| Command | Purpose |
35+
|---------|--------|
36+
| `npm test` | Run all Vitest tests |
37+
| `npm run build` | Development build |
38+
| `npm run build:production` | Production build |
39+
| `npm run content:assets` | Convert SVGs in `content/assets/` to PNGs |
40+
2941
## Template Collaboration Protocol
3042

3143
This plugin is part of the **stream-deck-template** knowledge-sharing ecosystem.
@@ -109,6 +121,22 @@ The template also maintains merged guides that this plugin may benefit from:
109121
|-------|-----|
110122
| Testing Protocol | `https://raw.githubusercontent.com/pedrofuentes/stream-deck-template/main/scaffold/.github/TESTING-PROTOCOL.md` |
111123
| UI/UX Design Guide | `https://raw.githubusercontent.com/pedrofuentes/stream-deck-template/main/scaffold/.github/UI-DESIGN-GUIDE.md` |
124+
| Marketplace Content | `content/CONTENT-GUIDE.md` (local) |
112125

113126
Read these before writing tests or making UI changes — they contain hardware-tested
114127
patterns and failure logs from multiple plugins.
128+
129+
## Post-Release — Update Elgato Marketplace Content
130+
131+
After every release, update the marketplace listing content:
132+
133+
1. Write release notes in `content/release-notes.md`
134+
2. Review `content/description.md` — update if features changed
135+
3. Update `content/marketplace-content.html` with matching HTML
136+
4. Update gallery SVGs in `content/assets/` if key display changed
137+
5. Run `npm run content:assets` to regenerate PNGs
138+
6. Commit content changes with the version bump
139+
7. After GitHub Release: open HTML file in browser, copy, paste into Elgato Marketplace WYSIWYG
140+
8. After GitHub Release: upload new asset PNGs if changed
141+
142+
See `content/CONTENT-GUIDE.md` for full details on asset requirements and procedures.

‎content/CONTENT-GUIDE.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# Marketplace Content Guide — Stream Deck iCal Plugin
2+
3+
This guide is for AI agents and contributors who maintain the Elgato Marketplace listing content for this plugin.
4+
5+
## Directory Structure
6+
7+
```
8+
content/
9+
├── CONTENT-GUIDE.md ← This file (agent instructions)
10+
├── description.md ← Plugin description (source of truth)
11+
├── release-notes.md ← Release notes per version (source of truth)
12+
├── marketplace-content.html ← Copy-paste ready HTML for WYSIWYG editor
13+
└── assets/
14+
├── icon.svg ← 288×288 plugin icon (source)
15+
├── icon.png ← Generated from SVG
16+
├── thumbnail.svg ← 1920×960 hero image (source)
17+
├── thumbnail.png ← Generated from SVG
18+
├── gallery-1-actions.svg ← 1920×960 all actions overview (source)
19+
├── gallery-1-actions.png ← Generated from SVG
20+
├── gallery-2-setup.svg ← 1920×960 setup flow (source)
21+
├── gallery-2-setup.png ← Generated from SVG
22+
├── gallery-3-states.svg ← 1920×960 key states (source)
23+
├── gallery-3-states.png ← Generated from SVG
24+
├── gallery-4-*.svg ← 1920×960 additional feature (source)
25+
└── gallery-4-*.png ← Generated from SVG
26+
```
27+
28+
## Source of Truth
29+
30+
| Content type | Source of truth | Format |
31+
|---|---|---|
32+
| Text (description) | `content/description.md` | Markdown |
33+
| Text (release notes) | `content/release-notes.md` | Markdown |
34+
| Copy-paste HTML | `content/marketplace-content.html` | HTML (manually synced from .md files) |
35+
| Images | `content/assets/*.svg` | SVG → PNG via script |
36+
37+
**Rules:**
38+
- Edit the `.md` files first, then update the HTML file to match.
39+
- Edit `.svg` files first, then run `npm run content:assets` to regenerate PNGs.
40+
- Never edit PNGs directly — they are generated artifacts.
41+
42+
---
43+
44+
## Elgato Marketplace Asset Requirements
45+
46+
| Asset | Format | Max Size | Dimensions | Aspect Ratio | Required |
47+
|-------|--------|----------|------------|--------------|----------|
48+
| **Icon** | PNG or JPG | 2 MB | 288 × 288 | 1:1 | Yes |
49+
| **Thumbnail** | PNG or JPG | 5 MB | 1920 × 960 | 2:1 | Yes |
50+
| **Gallery images** | PNG or JPG | 10 MB each | 1920 × 960 | 2:1 | Min 3 |
51+
| **Gallery video** | MP4 | 50 MB | 1920 × 1080 | 16:9 | Optional |
52+
| **Description** | Plain text / formatted | — | — | — | Yes, max 4,000 chars |
53+
| **Release Notes** | Plain text / formatted | — | — | — | Yes, max 1,500 chars per version |
54+
55+
---
56+
57+
## When to Update Each Asset
58+
59+
### Every Release
60+
- `content/release-notes.md` — Add new version entry
61+
- `content/marketplace-content.html` — Update the release notes tabs
62+
- `content/description.md` — Review; update if features changed
63+
64+
### Only When Actions/Display Changes
65+
- `content/assets/gallery-*.svg` — Update when key visuals change
66+
- `content/assets/thumbnail.svg` — Update when actions are added/removed
67+
- `content/assets/icon.svg` — Rarely changes (only for major rebrands)
68+
69+
### After Any Asset SVG Change
70+
- Run `npm run content:assets` to regenerate PNGs
71+
72+
---
73+
74+
## How to Write Release Notes
75+
76+
### Template
77+
78+
```markdown
79+
## vX.Y.Z — YYYY-MM-DD
80+
81+
Brief one-line summary of the release theme.
82+
83+
- Feature or change description (user-facing language)
84+
- Another change
85+
- Bug fix description
86+
87+
<!-- chars: ~NNN -->
88+
```
89+
90+
### Rules
91+
- **Most recent version first**
92+
- Only **user-facing changes** — skip internal refactors, test changes, docs-only changes
93+
- Use plain language: "Added support for..." not "feat: implement..."
94+
- Include character count comment (max 1,500 per entry)
95+
- Keep each entry self-contained — readers see one version at a time in the marketplace
96+
97+
### What to Include
98+
- New features and actions
99+
- Changed behavior
100+
- Fixed bugs users would notice
101+
- Removed features
102+
103+
### What to Exclude
104+
- Internal refactoring
105+
- Test additions/changes
106+
- Documentation-only changes
107+
- Dependency updates (unless they fix a user-visible issue)
108+
109+
---
110+
111+
## How to Update the Description
112+
113+
### Rules
114+
- Max **4,000 characters** (hard limit — the portal will reject more)
115+
- Include character count metadata at top of `description.md`
116+
- Marketing tone — highlight value, not implementation
117+
- Structure: Headline → Summary → Actions → Features → Requirements → Getting Started
118+
119+
### When Adding a New Action
120+
1. Add it to the "Actions" section in `description.md`
121+
2. Update the count ("three powerful actions" → "four powerful actions")
122+
3. Update the HTML file to match
123+
4. Consider updating gallery-1 SVG to show the new action
124+
125+
### When Adding a New Feature
126+
1. Add it to the appropriate section in `description.md`
127+
2. Update the HTML file to match
128+
3. Consider whether gallery images need updating
129+
130+
---
131+
132+
## How to Regenerate PNGs from SVGs
133+
134+
```powershell
135+
npm run content:assets
136+
```
137+
138+
This runs `scripts/convert-content-assets.ts` which:
139+
1. Reads all `.svg` files from `content/assets/`
140+
2. Converts each to PNG at native viewBox dimensions using `@resvg/resvg-js`
141+
3. Logs filename, dimensions, and file size
142+
4. Outputs PNGs alongside the SVGs
143+
144+
After running, verify:
145+
- Icon PNG ≤ 2 MB
146+
- Thumbnail PNG ≤ 5 MB
147+
- Gallery PNGs ≤ 10 MB each
148+
149+
---
150+
151+
## How to Update the HTML Copy-Paste File
152+
153+
The Elgato Marketplace uses a WYSIWYG editor that doesn't accept Markdown. The HTML file provides formatted content that can be copied and pasted directly.
154+
155+
### Steps
156+
1. Update the source `.md` file first
157+
2. Open `content/marketplace-content.html`
158+
3. Find the corresponding section
159+
4. Update the HTML to match the Markdown content
160+
5. Preserve formatting: `<strong>` for bold, `<ul>/<li>` for lists, `<h3>` for headings
161+
6. Test by opening in a browser — verify character counts are within limits
162+
163+
### Copy-Paste Workflow (for the user)
164+
1. Open `content/marketplace-content.html` in a browser
165+
2. Click inside the white content box for Description or the desired Release Notes tab
166+
3. Select all text in the box (Ctrl+A while focused in the box)
167+
4. Copy (Ctrl+C)
168+
5. Paste into the Elgato Marketplace WYSIWYG editor (Ctrl+V)
169+
6. Verify formatting preserved (bold, lists, headings)
170+
171+
---
172+
173+
## Visual Design Language
174+
175+
### Colors
176+
| Role | Color | Usage |
177+
|------|-------|-------|
178+
| Background dark | `#0d1117` | SVG backgrounds (dark end) |
179+
| Background mid | `#161b22` | SVG backgrounds (light end) |
180+
| Surface | `#1c2128` | Card/panel backgrounds |
181+
| Border | `#30363d` | Subtle borders |
182+
| Text primary | `#ffffff` | Headings, key text |
183+
| Text secondary | `#9ca3af` | Descriptions, labels |
184+
| Accent green | `#22c55e` | OK/normal state, features |
185+
| Accent orange | `#f97316` | Warning state (approaching meeting) |
186+
| Accent red | `#ef4444` | Urgent state (imminent meeting) |
187+
| Accent blue | `#3b82f6` | Links, info, time displays |
188+
| Key background | `#000000` | Stream Deck key face |
189+
190+
### Key Mockup Style
191+
- Black square with slightly rounded corners (4px radius at key scale)
192+
- Top accent bar: 2px colored line at top of key (green = normal, orange = warning, red = urgent)
193+
- White text centered, small font
194+
- Simulates the actual Stream Deck OLED key appearance
195+
196+
### SVG Layout Patterns
197+
- **Thumbnail**: Plugin name large left, tagline below, key mockups right, feature strip at bottom
198+
- **Gallery — Actions**: Simulated Stream Deck grid with all action keys populated
199+
- **Gallery — Setup**: Three-step flow with numbered circles and UI mockups
200+
- **Gallery — States**: Side-by-side key states showing color transitions
201+
202+
### Fonts
203+
- Use `system-ui, -apple-system, sans-serif` in SVGs for maximum compatibility
204+
- The resvg renderer will use system fonts — no custom fonts needed
205+
206+
---
207+
208+
## Release Workflow Checklist
209+
210+
When releasing a new version, add these steps after the GitHub Release:
211+
212+
1. [ ] Write release notes in `content/release-notes.md`
213+
2. [ ] Review `content/description.md` — update if features changed
214+
3. [ ] Update `content/marketplace-content.html` with matching HTML
215+
4. [ ] Update gallery SVGs in `content/assets/` if key display changed
216+
5. [ ] Run `npm run content:assets` to regenerate PNGs
217+
6. [ ] Commit content changes with the version bump
218+
7. [ ] After GitHub Release: open HTML in browser → copy → paste into Elgato Marketplace WYSIWYG
219+
8. [ ] After GitHub Release: upload new asset PNGs if changed
220+
221+
---
222+
223+
## Elgato Marketplace Upload Procedure
224+
225+
1. Go to the [Elgato Developer Portal](https://developer.elgato.com/)
226+
2. Sign in and navigate to your plugin listing
227+
3. **Description tab**:
228+
- Open `content/marketplace-content.html` in your browser
229+
- Copy the Description content from the white box
230+
- Paste into the WYSIWYG Description field
231+
- Verify character count ≤ 4,000
232+
4. **What's New tab**:
233+
- Copy the latest version's release notes from the HTML file
234+
- Paste into the WYSIWYG Release Notes field
235+
- Verify character count ≤ 1,500
236+
5. **Assets tab**:
237+
- Upload `content/assets/icon.png` as the Icon (288×288, ≤ 2 MB)
238+
- Upload `content/assets/thumbnail.png` as the Thumbnail (1920×960, ≤ 5 MB)
239+
- Upload `content/assets/gallery-*.png` files as Gallery images (1920×960, ≤ 10 MB each)
240+
- Ensure at least 3 gallery images
241+
6. **Upload** the `.streamDeckPlugin` package file
242+
7. **Submit** for review
243+
244+
---
245+
246+
## FAQ for Agents
247+
248+
### Q: Why is there both a Markdown file and an HTML file for text content?
249+
The Elgato Marketplace WYSIWYG editor doesn't accept Markdown. Markdown is the source of truth for easy editing. The HTML file is the delivery format for copy-pasting into the editor.
250+
251+
### Q: Why copy-paste instead of direct HTML upload?
252+
The Elgato portal doesn't accept raw HTML — it uses a WYSIWYG text editor. Copy-paste from a rendered HTML page preserves formatting (bold, lists, headings).
253+
254+
### Q: How do I know if the character count is correct?
255+
The HTML file includes live JavaScript character counters. Open it in a browser to see current counts. The metadata at the top of each `.md` file also tracks this.
256+
257+
### Q: Can I use the Cloudflare logo, Elgato logo, or other brand logos?
258+
**No.** Use only original artwork. No copyrighted logos or third-party brand marks.
259+
260+
### Q: The PNG is too large. What do I do?
261+
Simplify the SVG (remove gradients, reduce detail, use fewer elements). The resvg conversion is lossless PNG — complex SVGs produce large files.
262+
263+
### Q: Do I need to update all gallery images every release?
264+
No. Only update gallery images when the visual appearance of keys or UI changes. Text-only features don't require gallery updates.
265+
266+
### Q: What's the minimum number of gallery images?
267+
Three (3). The Elgato Marketplace requires at least 3 gallery images.

‎content/assets/gallery-1-actions.png‎

80.4 KB
Loading

0 commit comments

Comments
 (0)