Insert images and embeds

The Editor accepts three kinds of media — image files, video files, and external embeds (YouTube and Vimeo). This guide walks through every insertion path and explains what to expect after the upload completes.

Insert an image

Four routes, ranked roughly by how often you'll reach for them.

Drag-and-drop

1. Open your file manager next to the editor window.
2. Drag any image file onto the editor canvas.
3. Drop it where you want the image to appear.

Upload starts immediately; a placeholder shows while bytes stream. When the upload finishes, the real image renders in place — no page refresh needed.

Paste

1. Copy an image to the clipboard — a screenshot, a copy from a file manager, or copy-image from another browser tab.
2. Click in the editor where you want the image.
3. Press Ctrl+V (or Cmd+V on macOS).

Same upload flow as drag-and-drop.

Toolbar 🖼️

1. Click the 🖼️ icon below the main toolbar.
2. Pick a file from the OS file picker.
3. The image inserts at the current cursor position.

Programmatic (agent API)

For scripted imports, see the agent API docs. Workflow:

1. Upload the file via POST /api/kb/admin/blobs (multipart form field named file). The endpoint returns { id, url, contentType, byteSize }.
2. Reference the blob URL in your markdown body via <img src="/api/kb/blobs/<id>">.
3. Send the markdown via POST /api/kb/admin/articles/import.

Keep the URL relative — /api/kb/blobs/N rather than absolute. The chat-widget rewrites relative URLs against the kb-app origin so they resolve from any host.

Resize and align an image

Every inserted image has four corner handles (visible when the image is selected) plus a small side menu with three controls.

1. Click the image to select it. Corner handles and the side menu appear.
2. Drag any corner handle to scale. Aspect ratio is preserved automatically.
3. Use the side menu's alt text field to add an accessibility description. Short and concrete works best — describe what the image shows, not that it's an image.
4. Use align to choose Left, None, or Right:
   • None — the image renders as a full-width block (default).
   • Left — the image floats left; following text wraps around it on the right.
   • Right — the image floats right; following text wraps around it on the left.
5. Delete removes the image from the article body. The underlying blob row in kb_blob stays in the database for audit purposes — there's no UI to garbage-collect orphan blobs today.

Upload a video file

Video uses the same blob storage as images. Larger files take longer; 50 MB is the upload cap.

1. Click 📹 in the toolbar.
2. Pick a video file (MP4 and WebM are the universally-supported formats).
3. The video inserts as a <video controls preload="metadata"> player.

Readers see a poster frame and a play button. The browser only fetches the actual bytes when the user presses play — so a paused video won't blow your bandwidth budget.

The four corner-handle resize controls work on video the same way they work on image — drag to scale.

Embed YouTube or Vimeo

For anything already on YouTube or Vimeo, embed instead of uploading. You save the bandwidth and the original platform's view counts / analytics keep working.

1. Click 📺 in the toolbar. A modal opens with one URL field.
2. Paste the watch URL:
   • YouTube: https://www.youtube.com/watch?v=… or https://youtu.be/….
   • Vimeo: https://vimeo.com/….
3. Click Insert.

The editor converts the watch URL into the right embed URL automatically. The result is an <iframe> — and the sanitiser only allows iframes from www.youtube.com, www.youtube-nocookie.com, and player.vimeo.com. Every other host gets stripped on publish, so you cannot accidentally embed an arbitrary external site.

If the URL doesn't match a recognised pattern, the modal shows an inline error rather than inserting a broken iframe. Press Esc to cancel; click outside the dialog to dismiss.

Sanitisation

Every upload and every embedded iframe goes through server-side sanitisation when the article is published.

• Image content-types must start with image/ (50 MB cap, enforced by the blob endpoint).
• Video content-types must start with video/.
• iframe src must come from one of the three whitelisted hosts above. Other hosts are stripped silently — the iframe disappears from the published body.

If something seems to disappear after publish, the most common cause is a non-allowlisted iframe host. The sanitiser doesn't surface a warning today; if you suspect content was stripped, check the published body in the editor or the public reader.

Related

• The Editor — full toolbar tour.
• Editor keyboard shortcuts field definitions — every shortcut.
• Manage articles and folders — where to start a new article.