OmniDocHow to Add an Image to Markdown
Learn how to add images to Markdown with the standard image syntax and relative file paths, so pictures still show when the file is opened or converted.
If you write notes, documentation or reports in Markdown, you will eventually need a picture in the middle of the text. Adding one takes only a single line. The trouble usually starts later, when the file moves to another folder or gets converted to Word or PDF and the picture is missing or shows as a broken icon. In many cases the cause is a path that worked only on the computer where you typed it.
This guide explains how to add images to Markdown with the standard image syntax, how to write file paths that keep working, and how to confirm the picture survives when you convert or translate the file. It is written for anyone who uses Markdown, whether or not you have used OmniDoc before.
How do I add an image to Markdown? The short answer
Put the image in a folder next to your Markdown file, then insert it with an exclamation mark, alt text in square brackets, and a path such as images/your-file.png in parentheses. The rest of this guide covers the cases where that basic pattern needs adjusting.
| Your situation | What to do | Why |
|---|---|---|
| The image sits in a folder next to the .md file | Use an exclamation mark, bracketed alt text, then images/photo.png in parentheses | A relative path is resolved from the location of the Markdown file, so it works on any computer that has the same folder layout |
| The image is hosted online | Use the same pattern, but put a full web address starting with https in the parentheses | No local file is needed, but the picture breaks if the host removes or moves it |
| You need a specific width | Use an HTML img tag with a width attribute | Standard Markdown has no size syntax, and not every viewer honors the attribute |
| You use the same image in several places | Define a reference label once and point to it by name | You update the path in one place instead of every line |
Before you start
A few decisions made before you type the image line prevent many broken pictures later.
- Choose the image format. PNG, JPG, GIF and SVG are common choices for Markdown. Use a format your viewer or converter handles, and check the output if you are unsure, because support varies between tools.
- Decide where the Markdown file will live. Relative paths depend on the file's location. If you plan to move the file into a shared project folder, create the image folder inside that project now.
- Rename the image file. Use lowercase letters, numbers and hyphens, such as
sales-chart.png. Spaces and special characters cause broken links in some viewers. - Know which tool will display the file. A Markdown previewer, a web editor, and a converter can each handle images differently. Test in the tool you will actually use for the final version.
Adding an image to a Markdown file, step by step
- Create an image folder next to your .md file. Name it something simple like
images. Keeping pictures in one place makes paths easier to read and maintain. - Copy the image into that folder. Use the cleaned-up filename from the previous section so the path stays short and predictable.
- Find the spot in the text where the picture belongs. Put the image on its own line, separated from the paragraphs around it by a blank line, so it renders as a block.
- Type the image line. Start with an exclamation mark, then the alt text in square brackets, then the path in parentheses. For example, use the alt text Monthly sales bar chart followed by the path
images/sales-chart.pngin parentheses. - Write meaningful alt text. Describe what the picture shows in a few words, such as "bar chart of monthly sales, January to June." Alt text helps readers using screen readers and appears in place of the picture if it fails to load.
- Preview the file. Open the .md file in a Markdown previewer or the UniDoc web editor at app.unidoc.top, which supports Markdown. If the picture does not appear, check the path against the folder structure.
- Test a conversion with a short sample. Before you convert a long document, make a copy with one or two images and send it through the step you need. OmniDoc translation accepts Markdown files and keeps pictures in its output, so you can upload a test file on omnidoc.top and open the result to confirm each image appears.
Check the result
Once you have the converted or translated file, look at each picture and the text around it. The table below covers common problems.
| Check | How to see it | If it's wrong |
|---|---|---|
| The picture appears | Open the Markdown preview, or open the converted Word or PDF file | A broken icon usually means a typo in the path or a folder that moved. Compare the path with the real folder layout. |
| Alt text is present | Temporarily rename the image file and preview again | If the alt text does not show, check that the square brackets contain your description and are placed before the parentheses. |
| The picture survived conversion | Open the output and scroll to each image | If pictures are missing, make sure the image folder sat beside the .md file when you converted it, then run the conversion again. |
| The picture is the right size | Zoom in on the output and compare it with the page | If it is too large, resize the image file before inserting it, or use a width attribute in an HTML img tag. |
| Text near the picture reads correctly | Read captions and the sentences beside each image | Machine translation can change wording, so review captions and any important content yourself. |
📊 At a glance
There are three common ways to place a picture, and each suits a different job.
| Approach | Good fit when | Trade-off |
|---|---|---|
| Local relative path | The document lives in a project folder you keep together | The image moves only if its folder moves with the .md file |
| Web address | The image already lives on a site you control | The picture depends on that site staying online |
| HTML img tag with a width | You must control the displayed size | Some Markdown viewers ignore HTML, so the size may not carry over |
❓ FAQ
1. Can I resize an image in Markdown?
Standard Markdown syntax does not include a size setting. Resize the image file in an image editor before inserting it, or use an HTML img tag with a width attribute if your viewer supports it.
2. Can I add a caption under an image?
The basic image syntax has no caption field. Put a short line of italic text on the line directly below the image, or use the alt text as a description. Check the output, because caption placement depends on the tool you use.
3. Which image formats work in Markdown?
PNG, JPG, GIF and SVG are common choices. Support depends on the viewer or converter, so test the format in the tool you will use for the final file.
4. Do pictures carry over when I translate a Markdown file?
OmniDoc translation accepts Markdown and keeps pictures in its output. Upload a short test file first, open the result, and confirm that each image and its nearby text look right before you translate the full document.
📝 Summary
To add an image to Markdown, place the file in a folder beside your .md file and reference it with a relative path. Keep the file and its images together, write useful alt text, and check the output after every conversion so your pictures show up wherever the file goes.
