Images in Markdown
Learn how to add and format images in your Markdown documents
Adding Images to Markdown
Images can greatly enhance your Markdown documents by providing visual context, illustrations, or simply making your content more engaging. Markdown provides a simple syntax for embedding images that is similar to creating links. You can also use our Image Generator tool to easily create image syntax.
Basic Image Syntax
The basic syntax for adding an image in Markdown consists of an exclamation mark (!), followed by alt text in square brackets, and the image URL in parentheses:
When rendered, this will display the image with "Alt text" as the alternative text (for accessibility and when the image cannot be loaded).
Example image with alt text
You can also add a title attribute to your image, which will appear as a tooltip when a user hovers over the image:
Reference-Style Images
Similar to reference-style links, you can use reference-style syntax for images to keep your Markdown more readable, especially when using the same image multiple times:
![Alt text][image1]
[image1]: https://example.com/image.jpg "Optional title"This approach is particularly useful when you need to use the same image multiple times in your document or when you want to keep all your image URLs in one place for easier maintenance.
More Image Examples
Images with Links
You can make an image clickable by combining the image syntax with the link syntax:
[](https://example.com)When rendered, this will create an image that, when clicked, takes the user to the specified URL:
Clickable image (links to example.com)
Image Sizing and Alignment
Images are an important part of many Markdown documents. Markdown provides a simple syntax for adding images, with options for alt text, titles, and more. They can be combined with links to create clickable images and placed within tables for organized galleries.
Basic Markdown doesn't provide native syntax for controlling image size or alignment. However, you can use HTML within your Markdown for more control:
<img src="https://example.com/image.jpg" alt="Alt text" width="300" height="200" style="display: block; margin: 0 auto;">This HTML approach allows you to specify exact dimensions and center the image. Some Markdown processors also support custom syntax for image alignment and sizing.
Note: Support for HTML in Markdown varies between processors. Some platforms may restrict certain HTML elements or attributes for security reasons.
Local vs. Remote Images
You can reference both local images (stored in the same repository or file system) and remote images (hosted online):
// Remote image
// Local image (relative path)
// Local image (absolute path from repository root)
When using local images, be aware that the path is relative to the location of your Markdown file or based on how your Markdown processor handles paths.
Best Practices for Images
Image Best Practices
- Always include alt text - Alt text is essential for accessibility, helping screen readers describe images to visually impaired users. It also provides context when images fail to load.
- Optimize image file sizes - Large images can slow down page loading. Compress and resize images appropriately before including them in your Markdown documents.
- Use descriptive filenames - When using local images, choose descriptive filenames (e.g., "mountain-landscape.jpg" instead of "IMG_12345.jpg").
- Consider image formats - Use appropriate formats for different types of images: JPEG for photographs, PNG for graphics with transparency, SVG for vector graphics, and WebP for better compression.
- Provide image dimensions - When using HTML for images, specifying width and height helps browsers allocate space for images before they load, reducing layout shifts.
Common Mistakes to Avoid
Missing or Incorrect Syntax
// Missing exclamation mark (renders as link, not image) [Alt text](image.jpg) // Space between ! and [ (won't render correctly) ! [Alt text](image.jpg)Always use the correct syntax with an exclamation mark immediately followed by square brackets for alt text.
Broken Image Paths
// Incorrect relative path  // If image.jpg is not in the same directory // Using backslashes instead of forward slashes  // Use forward slashes even on WindowsDouble-check your image paths and always use forward slashes for paths, even on Windows systems.
Interactive Image Generator
Practice creating Markdown image syntax with our interactive generator. Try both inline and reference-style images!
Additional Resources
Official Markdown Specifications
Learn more about Markdown image syntax from the original specification and popular implementations.
Related Markdown Elements
Explore other Markdown elements that work well with images:
Useful Tools
Check out these tools to help you work with images in Markdown: