Markdown Images Guide (2026) – Syntax, Alt Text, Sizing, and Export Tips

Markdown image syntax is simple, but portable image workflows are not. If all you need is a basic inline image, standard Markdown is enough. If you care about captions, width control, relative paths, GitHub behavior, or clean Word/PDF export, you need to understand where CommonMark ends and where GitHub, Pandoc, or your export toolchain starts to differ.

Use this guide when you want to:

• add images without breaking export
• write better alt text instead of placeholder labels
• understand when a visible caption appears and when it does not
• choose between plain Markdown, HTML <img>, and Pandoc-style image attributes

Basic Markdown Image Syntax

The standard pattern is:

![Architecture overview](https://example.com/architecture.png)

You can also add an optional title:

![Architecture overview](https://example.com/architecture.png "System diagram")

This is the safest baseline for CommonMark and most Markdown editors.

Inline, Reference-Style, and Linked Images

Inline syntax is best for one-off images:

![Release checklist](https://example.com/checklist.png)

Reference-style images are cleaner in long documents:

![Release checklist][release-image]

[release-image]: https://example.com/checklist.png "Checklist"

If the image itself should be clickable, wrap the image in a link:

[![Open the full-size chart](https://example.com/chart-thumb.png)](https://example.com/chart-full.png)

That pattern is useful for thumbnails and dashboard screenshots.

Alt Text, Title, and Caption Are Not the Same Thing

This is where many Markdown guides stay too shallow.

alt text

alt text is the text replacement for the image. In CommonMark, the image description is normally rendered into the HTML alt attribute.

Bad:

![image](/diagram.png)

Better:

![Deployment diagram showing API, worker, and database flow](/diagram.png)

For accessibility and clarity:

1. describe the information the image carries
2. do not just write image, screenshot, or the file name
3. if the image triggers an action, describe the action or result, not just its shape

title

The optional quoted string in image syntax is metadata, not a guaranteed visible caption:

![Architecture overview](/diagram.png "System diagram")

Some renderers treat it like hover text. It is not a reliable replacement for a caption in exported documents.

caption

Basic Markdown image syntax does not create a visible caption by itself. If you need a visible caption, you usually need:

1. an HTML pattern such as <figure> / <figcaption>, if your renderer supports it
2. a Pandoc-compatible workflow, where a standalone image can become a figure

That distinction matters a lot in Word/PDF export.

Relative Paths vs Public URLs

This depends on context.

In repository docs

GitHub explicitly supports relative links and image paths in repository Markdown. If the image lives inside the same repo, relative paths are usually the right choice:

![UI states](/images/ui-states.png)

That keeps repo docs portable across branches and clones.

In exported documents or web tools

Relative paths are only safe if the export pipeline can still find the files. Once the document leaves the repo, relative images become much easier to break.

For shareable exports, use one of these:

1. a stable public https:// image URL
2. an uploaded asset inside the tool you are using
3. a build pipeline that packages the image alongside the Markdown

If the final file will travel outside your repo, relative paths are often the first thing to fail.

If the “image” is really a diagram or a formula snapshot, pause before you flatten it into a bitmap. In many documentation workflows, keeping the source as Mermaid or LaTeX math is easier to maintain than turning it into a screenshot too early.

How to Control Image Size

This is where people often get misled.

What standard Markdown gives you

Plain CommonMark image syntax gives you source, alt text, and optional title. It does not define a standard width/height syntax.

So if you write a guide that says “Markdown images support width control natively,” that is only true for some tools and extensions, not for Markdown in general.

When HTML <img> is the practical option

If your renderer allows inline HTML, this is often the most understandable fallback:

<img src="diagram.png" alt="Deployment diagram" width="640">

Use this when:

1. you need predictable width control
2. your workflow already accepts HTML in Markdown
3. you care more about output control than strict Markdown purity

GitHub also supports the <picture> element, but that is an HTML feature, not a universal Markdown feature.

If your real goal is export stability rather than browser-only styling, pair this section with Markdown Export Tips. Width control is only useful when the whole pipeline agrees on how the image should be carried into Word or PDF.

When Pandoc-style attributes are the better fit

If your workflow is Pandoc-compatible, image attributes are often cleaner than raw HTML:

![Deployment diagram](/diagram.png){ width=50% }

Pandoc supports width and height on images and accepts units such as:

• px
• cm
• mm
• in
• %

That is especially useful when the output target is not just HTML.

Pandoc Figures and Captions

This is one of the most useful non-obvious behaviors.

In Pandoc, an image with non-empty alt text that appears by itself in a paragraph can be rendered as a figure, using the image description as the caption:

![Architecture overview for the export pipeline](/diagram.png)

That is useful when you want a real figure-like block in PDF/Word workflows.

But if you only want a normal inline image, do not leave it alone in its own paragraph. Keep surrounding text with it, or use a renderer/workflow that treats it as inline.

This is not a generic Markdown rule. It is a Pandoc-specific behavior that matters because many export pipelines rely on Pandoc.

Practical md2word Advice

This section is based on the current md2word implementation, not generic web folklore.

1. Do not rely on local absolute paths in the web editor

Paths like these are not a good web workflow:

![Chart](/\Users\Ben\Desktop\chart.png)
![Chart](/Users/ben/Desktop/chart.png)

In the md2word web flow, local absolute paths are not treated as directly readable assets. Upload the image or use a stable https:// URL.

2. Remote image URLs are only as reliable as the host

If the host blocks downloads, times out, or the URL expires, export quality drops fast. If the image is important:

1. upload it into your workflow
2. avoid temporary signed URLs when possible
3. test one real export before sharing widely

In the current md2word export pipeline, a blocked local absolute path or a failed remote download does not behave like a harmless warning. The export step can fall back to a placeholder image instead of the original asset, so “it looked fine in source” is not enough.

3. Prefer explicit sizing when the final document matters

If an image must look right in Word/PDF, do not rely on “whatever the renderer decides.” Use either:

1. HTML <img width="..."> when your workflow supports inline HTML
2. Pandoc-style image attributes when your export pipeline supports them

4. Keep screenshots editorially useful

A giant screenshot is not automatically a useful image. Before export:

1. crop to the relevant area
2. use descriptive alt text
3. keep text inside the screenshot readable at document scale
4. avoid dumping multiple unrelated UI states into one image

5. Treat heavy image sets as a conversion risk

Many large images, many remote images, or both, make export slower and more fragile. If the document feels image-heavy, reduce it before sending it to final export.

Common Mistakes

1. Using alt as if it were a visible caption

It usually is not.

2. Assuming every Markdown renderer supports width syntax

They do not.

3. Copying repo-relative image paths into a document that will be exported and shared elsewhere

That works until the file leaves the repo.

4. Depending on local file system paths in a browser-based workflow

That is one of the fastest ways to get broken images.

5. Using vague alt text like image, diagram, or screenshot

That wastes the most important text field the image has.

FAQ

Should I use Markdown image syntax or HTML <img>?

Use plain Markdown for simple images. Use HTML <img> when you need explicit width/height control and your renderer allows inline HTML.

What is the safest choice for Word/PDF export?

A stable image source plus explicit sizing is usually the safest combination. For many export workflows, that means HTML <img> or Pandoc-style image attributes rather than plain image syntax alone.

Does the optional image title become a caption?

No. Treat it as optional metadata, not as a real caption strategy.

When should I use relative image paths?

Use them in repo-based documentation where the image is versioned together with the Markdown. For exported files and shareable documents, uploaded assets or stable public URLs are usually safer.

Why did my image work in preview but not in export?

Common causes include:

1. the image came from a local absolute path
2. the remote host blocked or expired the URL
3. the renderer accepted HTML or extensions in preview, but the export pipeline did not

Further Reading

• CommonMark Spec: Images
• GitHub Docs: Basic writing and formatting syntax
• Pandoc Manual: Images
• MDN: <img> element accessibility guidance

Changelog

• 2026-03-18: Initial high-value release with verified platform differences, sizing guidance, Pandoc figure behavior, and md2word export advice.
• 2026-03-19: Added stronger guidance on placeholder fallback behavior and when Mermaid or LaTeX source is safer than flattening diagrams into images.

Next steps: Explore Markdown Export Tips, Markdown Mermaid Guide, Markdown LaTeX Guide, Markdown Hyperlink, Markdown Table Guide, and Markdown Heading Guide.