Markdown Images: Paths, Alt Text, and Resizing Limits

Use ![description](image-url) to place an image in Markdown. The exclamation mark distinguishes an image from a normal link, the brackets contain alternative text, and the parentheses contain its address.

![Diagram showing the import and review steps](https://example.com/process.png)

The address above is an example, not an image supplied by this site. Replace it with an image you have permission to use. For the underlying syntax, see the CommonMark image rules.

Choose a path that exists where the document is rendered

Path	Meaning	What to check
https://example.com/chart.png	A remote image	Permissions, availability, and whether login is required
./assets/chart.png	A path relative to the published document	The matching directory and file must be present
/assets/chart.png	A path from the current website's root	It refers to that website, not your computer's disk
file:///Users/name/chart.png	A local file URL	Web applications commonly block it; it is not a portable sharing path

Importing a local .md file into MD File Viewer does not import the rest of the folder. A reference to ./assets/chart.png cannot automatically read a sibling file on your computer. In a repository, keep the image with the document and check the path in the repository's final preview.

Remote image requests reach the image host even when Markdown parsing happens in your browser. That host can receive normal request information, including the browser's network address. Review private documents for external images before rendering them, and use an approved local workflow when required.

Write alternative text for the image's purpose

Alternative text should convey the information a reader needs when the image is unavailable or cannot be seen.

![Import completed with 12 rows and no errors](./assets/import-result.png)

That is more useful than ![screenshot](...). For a purely decorative image, empty alternative text (![](...)) can be appropriate. For a complex chart, put its explanation or data in nearby prose or a table as well; a short label cannot communicate every data point.

A title such as ![result](result.png "Import result") is optional and may appear as a tooltip. It does not replace alternative text or a visible caption.

Make an image a link

Place the image expression inside a normal link:

[![Project overview](./assets/overview.png)](https://example.com/project)

Choose alternative text that explains the link's destination or purpose. Avoid making a decorative image look like a download or interactive button when it does not perform that action.

Set size at the destination

Standard Markdown image syntax has no width, height, or alignment parameter. Appending #w=200 or #h=100 to a URL is not a documented GFM image-sizing feature. A renderer may ignore such a fragment, so do not use it as a portable sizing command.

Options depend on the publishing environment:

• Resize the source image before publishing when a smaller asset is sufficient.
• Use CSS in a website whose styles you control.
• Use an HTML image with dimensions only if the platform permits that element and its attributes.
• Use a platform-specific extension only after checking that platform's documentation.

For an HTML-enabled destination, the idea is:

<img src="./assets/chart.png" alt="Quarterly import totals" width="600">

MD File Viewer removes raw HTML from user input, so this HTML example will not create a sized image in the tool's preview. Use normal Markdown image syntax here and test destination-specific sizing where you publish. The destination's CSS may constrain even a correctly loaded image to the available width.

Troubleshoot a missing image

Check the exact case and extension in the filename, then open the resolved URL where the document is published. A local file or authenticated dashboard URL may be unavailable to other readers. A remote host can also prevent embedding or cross-origin capture.

For filenames with spaces, encode the space as %20, or use an angle-bracket destination such as ![diagram](<assets/my diagram.png>) in a compatible renderer. Do not put an unescaped space into a bare destination and assume every parser will accept it.

An image can appear in the web preview yet be absent from an export if its host does not permit capture or fetching. Open the actual Word, PDF, or image output and check it. The Word guide and image export guide explain those separate limitations.

Keep the original source, the image files, and their usage permissions together so the document can be maintained later.