Media Embeds

OnyxFolio converts ![[filename]] embed syntax into lightbox images, image sliders, video players, and audio players. All media is served directly from your vault.

Where to put files

Media files go in an _attachments/ subfolder relative to the note's folder:

If the file isn't found in the section's _attachments/, OnyxFolio falls back to the vault-root _attachments/, then to ATTACHMENTS_PATH from .env. See Attachments for the full resolution order.

Single image

![[photo.jpg]]

Renders as a lightbox image. Click to open full-screen.

With caption

![[photo.jpg|Caption text here]]

Renders with a <figcaption> below the image.

With fixed width (pixels)

![[photo.jpg|600]]

A numeric-only value is treated as a pixel width, not a caption. The image is constrained to that width.

Image gallery (lightbox)

Place multiple embeds on separate lines to create a thumbnail gallery. Clicking any image opens the lightbox viewer:

![[photo1.jpg]]
![[photo2.jpg]]
![[photo3.jpg]]

Image slider

Place multiple embeds on a single line (space-separated) to create a swipeable slider:

![[photo1.jpg]] ![[photo2.jpg]] ![[photo3.jpg]]

Renders with left/right arrows and dot navigation.

Video

![[video.mp4]]

Supported formats: .mp4, .webm, .mov. Renders as an HTML5 <video> element with controls.

Audio

![[track.mp3]]

Supported formats: .mp3, .ogg, .wav, .flac, .m4a. Renders as an HTML5 <audio> element with controls.

Missing media

If the file cannot be found in any of the attachment locations, OnyxFolio renders:

<em>Missing media: filename.jpg</em>

No broken image icons. Check the attachment folder structure if this appears.

Security note

OnyxFolio validates that resolved file paths stay within the vault directory. Symlinks or paths that escape the vault are rejected and render as missing.

See also

• Attachments — resolution order and fallback paths
• Note Transclusion — embedding other notes inline (not media files)