Markdown Images: Syntax, Paths, Size, and Alt Text

To add an image in Markdown, type an exclamation mark, put alternative text in square brackets, and put the image path or URL in parentheses: ![Alt text](image.png). The syntax is simple; choosing the right path and useful alt text is where most problems begin.

![Hashdraft showing Markdown in Split mode](images/hashdraft-split.png)

Basic Markdown image syntax

An inline Markdown image has three required parts:

![Alternative text](path-or-url)

• ! tells the parser to embed an image rather than create a text link.
• Alternative text describes the meaningful information in the image.
• The destination tells the renderer where to find the image file.

You can add an optional title after the path. Some renderers show it as a tooltip:

![A settings panel](images/settings.png "Hashdraft settings")

Do not use the title as a substitute for alt text. Titles are inconsistently exposed on touch devices and to assistive technology.

Local paths, relative paths, and image URLs

The best path depends on where the document will live. A local note, a GitHub README, and a published website have different roots.

Why relative paths are usually better

A relative path describes the image location in relation to the Markdown file. If you move or clone the whole project, the relationship stays intact. A Windows path such as C:\Users\Name\Desktop\image.png only works on one computer and should not appear in shared Markdown.

Use forward slashes in Markdown paths, including on Windows:

![Correct](images/screenshots/app.png)
![Avoid](images\screenshots\app.png)

Spaces and special characters

Simple lowercase filenames are easiest to maintain. Prefer split-mode.png to Split Mode Final (2).png. If a URL or path contains a space, encode it as %20 or rename the file:

![Quarterly chart](images/Q2%20chart.png)

Filename capitalization can also break after a project moves from Windows to a case-sensitive server. Match the exact case even when Windows appears to tolerate a mismatch.

How to write useful image alt text

Alt text communicates the image's purpose when the image cannot be seen or loaded. Describe the information a reader needs in the context of the surrounding paragraph.

Avoid “image of” and “picture of” unless the fact that it is a photograph or illustration matters. Do not repeat a caption word for word. If an image contains substantial data, summarize the conclusion in the surrounding prose as well.

Reference-style images

Reference syntax keeps long URLs away from the main sentence and makes repeated assets easier to update:

![Hashdraft icon][app-icon]

[app-icon]: images/hashdraft-icon.png "Hashdraft"

Inline and reference images render the same way. Use whichever keeps the source easier to read.

Make a Markdown image clickable

Wrap the entire image inside normal link syntax:

[![Hashdraft preview](images/hashdraft-preview.png)](https://github.com/necromind/hashdraft)

The inner ![]() embeds the image; the outer []() supplies the destination. Make sure the alt text describes the image or link purpose, not “click here.”

Resize an image in Markdown

Core Markdown does not define width, height, alignment, or responsive image attributes. This is intentional: Markdown describes content structure while the renderer controls presentation.

If raw HTML is allowed, use an HTML image element:

<img src="../../images/diagram.png"
     alt="Data flow from source to preview"
     width="640">

HTML support varies, and some platforms sanitize attributes. Other renderers provide product-specific extensions such as {width=50%}, but those reduce portability. For a document that must work everywhere, resize or optimize the source file and let the renderer limit it to the reading column.

Add a caption or figure

Basic Markdown has no universal figure-caption syntax. A simple portable pattern is an image followed by italic text:

![Hashdraft in Split mode](images/hashdraft-split.png)

*Source and rendered document stay synchronized.*

If the destination supports HTML, a semantic <figure> and <figcaption> provide a stronger relationship. Publishing systems such as Pandoc may also have figure-specific extensions.

Choose the right image format

• PNG: interface screenshots, diagrams, and graphics with sharp edges or transparency.
• JPEG: photographs where smaller files matter more than lossless detail.
• WebP or AVIF: efficient web delivery when every destination supports the format.
• SVG: logos and vector diagrams, subject to renderer and security restrictions.

Large source images make repositories heavy and can slow preview, export, and page loading. Crop screenshots to the useful area, remove unnecessary metadata, and export at a resolution appropriate for the final reading size.

Images in GitHub Markdown

For images stored in the same repository, use relative paths so they work across branches and local clones. GitHub also allows dragging or pasting images into issues, pull requests, and discussions, which uploads the asset and inserts Markdown automatically.

A relative path in a README is resolved from that file. If README.md and an images folder share the repository root, use:

![Application overview](images/application-overview.png)

Images when exporting Markdown to PDF

A PDF converter must be able to access the image at export time. Local project images are usually more reliable than remote URLs. Before export, confirm that every image appears in Preview and has enough resolution for the physical page size.

If a wide image becomes unreadably small, crop it, split it into panels, or use a landscape page in a configurable publishing pipeline. Continue with the Markdown-to-PDF guide.

Why a Markdown image is not showing

1. Check the filename and case. Diagram.png and diagram.png may be different files after publishing.
2. Resolve the path from the Markdown file. Do not calculate it from the folder currently open in a terminal unless the tool explicitly works that way.
3. Replace backslashes with forward slashes.
4. Remove or encode spaces.
5. Confirm the asset was copied or committed.
6. Check permissions and network access for remote or private images.
7. Test the destination renderer. SVG, HTML attributes, data URLs, and product-specific sizing may be blocked.

Frequently asked questions