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.
100 lines
4.6 KiB
Markdown
100 lines
4.6 KiB
Markdown
---
|
||
name: add-docs-image
|
||
description: 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`/`.jpg` from a page.
|
||
- **Path: root-relative.** Reference as ``, NOT `/apps/docs/public/...` and NOT a relative path.
|
||
The file goes in `apps/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 keeps `apps/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:
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```mdx
|
||
|
||
```
|
||
|
||
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
|
||
|
||
```bash
|
||
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/`:
|
||
|
||
```bash
|
||
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.
|