Skip to content
Docs
Developer Codex
Pages & Editor

Image Blocks

Image blocks are a first-class content type in Inklings — not an editor plugin, but a built-in element alongside text blocks. An image block stores the attachment reference, layout metadata, and caption independently from the text content around it.

Before you start

Section titled “Before you start”

An image block references an attachment — a file uploaded to your workspace. Before inserting an image block, the image needs to exist as an attachment.

Upload an image via the Attachments panel (or by dragging an image file into the editor, if drag-and-drop is configured for your workspace). Once uploaded, the attachment has a UUID that the image block references.

Insert an image block

Section titled “Insert an image block”
  1. Click in the editor body where you want the image to appear.
  2. Press / to open the insert menu, or use the toolbar’s insert action.
  3. Select Image Block from the menu.
  4. Choose the attachment from the picker.

The image block appears in the editor at that position. By default, it renders at full width (FitWidth scale) and centered alignment.

Set a caption

Section titled “Set a caption”

Click the image block to open its options. Enter a caption in the caption field.

The caption serves two purposes:

  • It appears below the image in the editor as a visible label
  • It becomes the alt text in the Virtual File System — a feature that lets you browse your workspace as ordinary files on your computer (overriding the block’s alt text field when non-empty)

The caption maximum length is 500 characters.

Set alt text

Section titled “Set alt text”

If you don’t set a caption, the alt text field on the block is used instead. This text:

  • Does not appear visually below the image
  • Is indexed by the full-text search system — so a page is findable by its image’s alt text
  • Becomes the alt text in the Virtual File System markdown output

If both a caption and alt text are set, the caption takes precedence for alt text in the Virtual File System output. Both fields contribute to search indexing.

Adjust scale and alignment

Section titled “Adjust scale and alignment”

Three scale options are available:

  • Fit Width (default) — the image stretches to fill the available column width
  • Original Size — the image renders at its actual pixel dimensions
  • Percentage — the image renders at a percentage of the column width (1–100%)
Section titled “Add a link URL”

An image block can carry an optional link URL. When set, clicking the image navigates to that URL. The URL must use http:// or https:// — other schemes are rejected.

Multiple images on one page

Section titled “Multiple images on one page”

A page can contain any number of image blocks. Each has its own independent metadata — caption, scale, alignment, and attachment reference. They appear in the order they were created, which you can reorder by moving blocks within the editor.

Section titled “Image blocks in search”

Images contribute to full-text search through their text content:

  • When only alt text is set, the alt text is indexed
  • When a caption is set, both the alt text and caption are indexed

Searching for a word that appears in a caption or alt text surfaces the page containing that image in search results.

Image blocks in VFS markdown

Section titled “Image blocks in VFS markdown”

If you use the Virtual File System to access your workspace as files, image blocks project as standard markdown image syntax:

![alt text or caption](attachments/uuid)

The UUID in the path is the attachment’s identifier. Brackets in the alt text are automatically escaped to preserve valid markdown syntax.

See Also

Section titled “See Also”

Was this page helpful?