Skip to content

Commit 3219ebd

Browse files
srnicholssrnichols
committed
docs: improve sample galleries layout and strengthen gallery validator
1 parent 60bfe49 commit 3219ebd

File tree

4 files changed

+91
-33
lines changed

4 files changed

+91
-33
lines changed

‎SAMPLE_GALLERIES.md‎

Lines changed: 38 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,49 @@
11
# Sample Galleries Index
22

3-
This page links to screenshot galleries for sample apps and the management portal to make them easier to discover.
3+
A visual index of sample app galleries and the management portal. Click a card to open the gallery page with full-size screenshots and captions.
44

55
## Galleries
66

7-
### Management Portal
8-
9-
[![Management Portal thumbnail](management-portal/docs/thumbnails/ManagmentPortal-Dashboard-Screenshot-thumb.png)](management-portal/docs/SCREENSHOTS.md)
10-
11-
- Link: [Management Portal screenshots](management-portal/docs/SCREENSHOTS.md)
12-
13-
### TaskTracker Sample
14-
15-
[![TaskTracker thumbnail](samples/tasktracker/docs/thumbnails/TaskTrack-HomePage-screenshot-thumb.png)](samples/tasktracker/docs/SCREENSHOTS.md)
16-
17-
- Link: [TaskTracker screenshots](samples/tasktracker/docs/SCREENSHOTS.md)
18-
7+
<style>
8+
/* lightweight responsive grid for markdown viewers */
9+
.gallery-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:20px;align-items:start}
10+
.gallery-card{background:#fff;border-radius:8px;padding:12px;box-shadow:0 6px 18px rgba(0,0,0,0.06);transition:transform .12s ease}
11+
.gallery-card:hover{transform:translateY(-4px)}
12+
.gallery-thumb{width:100%;height:auto;border-radius:6px;display:block}
13+
.gallery-title{margin:10px 0 4px 0;font-size:1.05rem}
14+
.gallery-desc{margin:0;color:#6b7280;font-size:0.95rem}
15+
</style>
16+
17+
<div class="gallery-grid">
18+
<a class="gallery-card" href="management-portal/docs/SCREENSHOTS.md">
19+
<img class="gallery-thumb" src="management-portal/docs/thumbnails/ManagmentPortal-Dashboard-Screenshot-thumb.png" alt="Management Portal dashboard thumbnail" />
20+
<div>
21+
<div class="gallery-title">Management Portal</div>
22+
<div class="gallery-desc">Overview dashboard, tenant and cell management screenshots.</div>
23+
</div>
24+
</a>
25+
26+
<a class="gallery-card" href="samples/tasktracker/docs/SCREENSHOTS.md">
27+
<img class="gallery-thumb" src="samples/tasktracker/docs/thumbnails/TaskTrack-HomePage-screenshot.png" alt="TaskTracker home page thumbnail" />
28+
<div>
29+
<div class="gallery-title">TaskTracker</div>
30+
<div class="gallery-desc">TaskTracker sample app UI screenshots (home, new task, edit task).</div>
31+
</div>
32+
</a>
33+
34+
</div>
35+
36+
---
1937

2038
## How to add a gallery
2139

2240
1. Create a `docs/SCREENSHOTS.md` in your sample folder.
2341
2. Add images to the same folder and (optionally) a `thumbnails/` subfolder.
24-
3. If you want automated thumbnails, add or reuse `.github/workflows/generate-thumbnails.yml` and the helper script `management-portal/docs/generate-thumbnails.ps1`.
42+
3. To validate galleries locally, run:
43+
44+
```powershell
45+
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-galleries.ps1
46+
```
47+
48+
This script checks all `SCREENSHOTS.md` files in the repo for missing image references.
2549

‎docs/DOCS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ A complete index of the documentation set. Use this as a quick catalog and to ve
4848
- [PARAMETERIZATION_GUIDE.md](./PARAMETERIZATION_GUIDE.md) - Configuration parameters
4949
- [RBAC_CHEATSHEET.md](./RBAC_CHEATSHEET.md) - Role-based access control reference
5050
- [REPOSITORY_MAP.md](./REPOSITORY_MAP.md) - Repository structure guide
51+
- [SAMPLE_GALLERIES.md](./SAMPLE_GALLERIES.md) - Sample app galleries and screenshots
5152
- [SECRETS_AND_CONFIG.md](./SECRETS_AND_CONFIG.md) - Configuration management
5253
- [SECURITY_GUIDE.md](./SECURITY_GUIDE.md) - Security implementation
5354
- [TROUBLESHOOTING_PLAYBOOKS.md](./TROUBLESHOOTING_PLAYBOOKS.md) - Operational playbooks

‎management-portal/docs/SCREENSHOTS.md‎

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -64,22 +64,3 @@ Images live in `management-portal/docs` — you can link to them from other docs
6464

6565
---
6666

67-
## How to regenerate thumbnails locally
68-
69-
I included a PowerShell helper `generate-thumbnails.ps1` in this folder that uses ImageMagick to create thumbnails (300px wide by default). Run it from this folder like:
70-
71-
```powershell
72-
powershell -NoProfile -ExecutionPolicy Bypass -File .\generate-thumbnails.ps1 -Width 300
73-
```
74-
75-
The script writes thumbnails to `management-portal/docs/thumbnails` with the `-thumb` suffix.
76-
77-
## CI / automated generation
78-
79-
A GitHub Actions workflow (.github/workflows/generate-thumbnails.yml) is included. It runs on push and on manual dispatch and will generate thumbnails and push them back to the repository automatically.
80-
81-
## Notes and tips
82-
83-
- If images are large, thumbnails speed up page rendering; clicking a thumbnail opens the full image.
84-
- For accessibility, edit the `alt` text and captions to be more descriptive if needed.
85-
- If you want different thumbnail sizes or a different filename convention, edit `generate-thumbnails.ps1` and the workflow accordingly.

‎scripts/validate-galleries.ps1‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<#
2+
Validate galleries script - checks that SCREENSHOTS.md files reference images that exist.
3+
Run locally from repo root:
4+
pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/validate-galleries.ps1
5+
#>
6+
7+
$errors = @()
8+
9+
Get-ChildItem -Path . -Recurse -Filter SCREENSHOTS.md | ForEach-Object {
10+
$md = $_.FullName
11+
Write-Output "Checking: $md"
12+
$content = Get-Content $md -Raw
13+
# remove fenced code blocks so example markup isn't validated
14+
$content = [regex]::Replace($content, '```[\s\S]*?```', '', 'Singleline')
15+
# find image references: ![alt](path) or <img src="path"
16+
$pattern1 = '!\[[^\]]*\]\(([^)]+)\)'
17+
$pattern2 = '<img[^>]*src\s*=\s*"([^"]+)"'
18+
foreach ($m in [regex]::Matches($content,$pattern1)){
19+
$path = $m.Groups[1].Value
20+
# skip URLs
21+
if ($path -match '^(https?:)?//') { continue }
22+
$p = Join-Path (Split-Path $md -Parent) $path
23+
if (-not (Test-Path $p)){
24+
# try relative to repo root as some docs include repo-root relative paths
25+
$repoRoot = (Resolve-Path .).Path
26+
$p2 = Join-Path $repoRoot $path
27+
if (-not (Test-Path $p2)){
28+
$errors += "Missing image referenced in $($md): $($path)"
29+
}
30+
}
31+
}
32+
foreach ($m in [regex]::Matches($content,$pattern2)){
33+
$path = $m.Groups[1].Value
34+
if ($path -match '^(https?:)?//') { continue }
35+
$p = Join-Path (Split-Path $md -Parent) $path
36+
if (-not (Test-Path $p)){
37+
$repoRoot = (Resolve-Path .).Path
38+
$p2 = Join-Path $repoRoot $path
39+
if (-not (Test-Path $p2)){
40+
$errors += "Missing image referenced in $($md): $($path)"
41+
}
42+
}
43+
}
44+
}
45+
46+
if ($errors.Count -gt 0){
47+
Write-Error "Validation failed - missing images:`n$($errors -join "`n")"
48+
exit 1
49+
}
50+
else{
51+
Write-Output "All gallery images are present."
52+
}

0 commit comments

Comments
 (0)