Add Images to Help Articles

When to use images

Use images when a visual callout will help staff find a control, understand a form, or recognize a workflow state. Screenshots are most useful when they are cropped or annotated around the exact control being explained.

Add an image

1. Open an existing article in edit mode, or select New article to start a draft.

2. Place the cursor where the image should appear in the body.

3. Select the image button in the TipTap toolbar, then choose an image file. You can also drag an image into the editor body.

4. Wait for the upload to finish and confirm the image appears in the article body.

5. Add explanatory text before or after the image so staff know what the callout is showing.

6. Save the article.

Supported image files

• Topo accepts PNG, JPEG, GIF, WebP, and SVG images.

• Each image must be under 10 MB.

• Uploaded images are stored through Topo's ActiveStorage setup and inserted into the TipTap body as image nodes.

Common errors

• Unsupported image type means the file is not one of the accepted image formats.

• Image must be under 10 MB means the screenshot or file needs to be compressed, resized, or cropped before uploading.

• If an image looks blank or does not render, upload the file through the editor instead of pasting an arbitrary external image URL. The renderer only allows safe ActiveStorage image URLs and a small set of trusted embed hosts.

• If the article is still a new draft, save it before leaving the page so the uploaded image remains part of the article content.

Screenshot quality checklist

• Crop out unrelated white space and side navigation unless it helps orient the reader.

• Use callouts, boxes, or arrows to point to the exact control.

• Do not include member personal information, payment details, API keys, or internal incident details unless the article visibility and purpose require it.

• Keep the image near the step it supports, not at the very top or bottom of the article by default.