Rotimi Best
81294a47f9
Adds live-class session scheduling on lessons (join link, date/time, timezone) with automatic 24h and 1h reminder emails plus a calendar invite (.ics), a time-change notification with an updated invite, a teacher-authored welcome email and session invite on enrollment, and a "Notify students" quiz nudge. LMS gets an upcoming live-sessions card and Join buttons, plus a reusable live-session card component (3 states) in @cio/ui with a Storybook story. The sidebar content tree now reflects sequential progression locking like the content list, and the course-completion confetti regression is fixed. Org-based emails no longer reference ClassroomIO by name. Docs add live-class, welcome-email, and course-progression guides, expand the certificates guide (design, signatures, corrected labels), move plan-required callouts to the top, flatten how-to-guides to the docs root with redirects, and add screenshots. Includes an add-docs-image skill.
4.6 KiB
name, description
| name | description |
|---|---|
| add-docs-image | Add screenshots/images to ClassroomIO docs — convert source PNGs to optimized WebP, place them in apps/docs/public/, and reference them from the .mdx pages under apps/docs/content/docs/. Use when a doc page needs annotated screenshots or other images. |
You are adding images to the ClassroomIO docs site (Fumadocs). Pages live in apps/docs/content/docs/*.mdx
and images live in apps/docs/public/, referenced with root-relative paths like /my-image.webp.
The job has three parts: optimize + convert the source image to WebP, drop it in apps/docs/public/, and
insert a Markdown image reference at the right spot in the page. Match the existing images exactly so the page
stays consistent.
Conventions (match these)
- Format: WebP. Every docs image is
.webp. Never reference a.png/.jpgfrom a page. - Path: root-relative. Reference as
, NOT/apps/docs/public/...and NOT a relative path. The file goes inapps/docs/public/name.webp; the leading/resolves to that folder. - Filename: kebab-case, prefixed by the page/feature. e.g.
certificates-rules.webp,live-class-session-settings.webp,progression-locked.webp. This keepsapps/docs/public/self-describing. - Size: width capped at 1280px (shrink only), quality ~80, metadata stripped. Existing images land around 20–45 KB at 1280px wide. Source screenshots (often retina, ~1 MB) must be reduced — do not commit raw PNGs.
- Alt text: descriptive, sentence-case, no period. Describe what the screenshot shows (and the highlight if
any), e.g.
Certificate rules panel with the download toggle and completion threshold. Some existing alt text notes an annotation, e.g.... with a red box highlight on the add icon.
Step 1: Find and identify the source images
Source images are usually PNGs the user dropped in ~/Downloads. List them:
ls -lt ~/Downloads/*.png | head
If the user named them to match the target (e.g. certificates-rules.png), the mapping is direct. Otherwise open
each with the Read tool (it renders images) and match it to the intended target by content. If you cannot
confidently match an image, ask rather than guess.
Step 2: Convert + optimize to WebP
Check the tool (command -v magick cwebp). Prefer ImageMagick. The 1280> only shrinks images wider than 1280
(never upscales):
magick "$SRC" -resize '1280>' -strip -quality 80 "apps/docs/public/$NAME.webp"
cwebp fallback (only pass -resize when the source is wider than 1280, since cwebp -resize upscales smaller images):
cwebp -q 80 "$SRC" -o "apps/docs/public/$NAME.webp" # width <= 1280
cwebp -q 80 -resize 1280 0 "$SRC" -o "apps/docs/public/$NAME.webp" # width > 1280
Confirm the result is sane (roughly 1280px wide, tens of KB), and never delete the original from ~/Downloads:
magick identify -format '%wx%h %b\n' "apps/docs/public/$NAME.webp"
To benchmark against existing images: ls -la apps/docs/public/*.webp (most are 1280px wide, ~20–45 KB).
Step 3: Insert the reference into the page
Add the image on its own line, with a blank line before and after, at the most useful spot:
- Under a section heading — right after the section's intro sentence, before any
<Steps>block. - Inside a
<Step>— after that step's instruction, so the screenshot illustrates that exact action. - After the relevant paragraph — e.g. a "What students see" view goes right after the sentence describing it.
One screenshot per distinct UI/action. Do not stack multiple images with no text between them; give each a home next to the step or paragraph it supports.
Step 4: Format and verify
pnpm exec prettier --write apps/docs/content/docs/<page>.mdx
Verify every image reference on the page resolves to a real file in apps/docs/public/:
grep -hoE '\(/[A-Za-z0-9._-]+\.webp\)' apps/docs/content/docs/<page>.mdx \
| tr -d '()' | while read -r p; do [ -f "apps/docs/public$p" ] && echo "OK $p" || echo "MISSING $p"; done
All lines should print OK. Report the files added, their final WebP sizes, and any source image you could not
confidently match.
Don'ts
- Don't reference a PNG/JPG from a page, or point at
apps/docs/public/...instead of/.... - Don't commit oversized images — always run the resize/quality pass.
- Don't upscale a smaller source to 1280.
- Don't delete the user's originals in
~/Downloads. - Don't invent an image for UI that does not exist; only document what you can see in a real screenshot.