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.
|