What is the difference between a Markdown link and an image?

Image syntax is identical to link syntax except for an exclamation mark (`!`) prefix. A link is `[Anchor](url)`, whereas an image is `![Alt text](image-url)`. The exclamation mark instructs the Markdown renderer to display the media inline.

How do I resize an image in standard Markdown?

Standard CommonMark does not define image resizing. However, Obsidian and Oyma support pipe dimensions (`![[image.png|300]]` or `![alt](image.png|300x200)`). Alternatively, standard HTML ` ` can be used.

Why is alt text critical when embedding Markdown images?

Alt text describes the image for screen readers, ensuring accessibility for visually impaired readers. It also serves as fallback text if the image file fails to load or the file path is broken.

How are pasted images stored in Oyma?

When you paste or drop an image into Oyma, the file is saved automatically into an `attachments/` folder on your local Mac disk and linked via relative Markdown embed syntax (`![[attachments/image.png]]`).

Markdown Images: Syntax, Alt Text & Sizing Guide

Primary SyntaxCommonMark

![Alt description](path/to/image.png)
![Alt text](image.png "Caption")
![[image.png|300]]

Visual assets—diagrams, system architecture blueprints, meeting whiteboards, product mockups, and screenshots—enrich documentation and clarify complex concepts.

Markdown provides a straightforward syntax for embedding images directly into documents. CommonMark handles both remote web images and local filesystem assets, while Oyma and Obsidian add powerful dimension resizing and frictionless drag-and-drop embedding.

Standard Markdown image syntax

The standard CommonMark image syntax closely mirrors hyperlink syntax, differentiated by a leading exclamation mark (!):

![Alt text description](https://example.com/images/architecture.png)

This compiles to the HTML element: <img src="https://example.com/images/architecture.png" alt="Alt text description" />.

Adding optional image titles (Captions / Tooltips)

Just like links, you can append an optional title string in quotation marks after the image path:

![System diagram](assets/diagram.png "Figure 1: Client-side local architecture")

The title attribute displays as a hover tooltip in web browsers and can be styled by documentation generators as an automatic figure caption.

Referencing local images in your notes vault

In local-first knowledge bases like Oyma, images reside on your local Mac disk rather than on external web servers. You reference them using relative file paths:

![Architecture flow](./assets/system-diagram.png)
![Quarterly financial chart](../attachments/q3-revenue.jpg)

Relative paths ensure that your images remain permanently linked when you move your vault, back it up to Time Machine, or synchronize it via Git.

Image resizing syntax in Oyma and Obsidian

Standard CommonMark does not support image dimensions, forcing web writers to fall back to verbose HTML tags (<img src="..." width="400" />).

In Oyma and Obsidian, you can control image dimensions directly in Markdown using the pipe delimiter (|):

Setting width in pixels

![Architecture diagram|400](assets/architecture.png)

This scales the image to 400 pixels wide while automatically preserving the original aspect ratio.

Setting width and height

![Screenshot|600x400](assets/screenshot.png)

This constrains the image to a bounding box of 600px wide by 400px high.

Obsidian double-bracket transclusion

Oyma also natively supports Obsidian-style wikilink embeds:

![[attachments/whiteboard-notes.png|500]]

Making images clickable (Image links)

You can wrap an image inside a standard Markdown link to create a clickable image that opens a larger version or an external website:

[![Click to view full architecture](assets/thumb.png)](https://www.getoyma.com/privacy-architecture)

The inner ![thumb](...) serves as the anchor content for the outer [...](url) link.

Working with images in Oyma

Handling images in Oyma on macOS is completely frictionless:

Paste from clipboard: Press ⌘V with any copied image to insert it directly into your note.
Drag and drop: Drag image files from Finder directly into your text.
Local storage: Oyma saves the asset to your local attachments/ folder on disk. No third-party cloud hosting is used.
Live preview: Images render instantly in the editor at native Retina resolution with smooth rounded corners and crisp scaling.

Frequently asked questions

What is the difference between a Markdown link and an image?: Image syntax is identical to link syntax except for an exclamation mark (`!`) prefix. A link is `[Anchor](url)`, whereas an image is `![Alt text](image-url)`. The exclamation mark instructs the Markdown renderer to display the media inline.
How do I resize an image in standard Markdown?: Standard CommonMark does not define image resizing. However, Obsidian and Oyma support pipe dimensions (`![[image.png|300]]` or `![alt](image.png|300x200)`). Alternatively, standard HTML `` can be used.
Why is alt text critical when embedding Markdown images?: Alt text describes the image for screen readers, ensuring accessibility for visually impaired readers. It also serves as fallback text if the image file fails to load or the file path is broken.
How are pasted images stored in Oyma?: When you paste or drop an image into Oyma, the file is saved automatically into an `attachments/` folder on your local Mac disk and linked via relative Markdown embed syntax (`![[attachments/image.png]]`).