Markdown Images: How to Embed, Sizing & Alignment
Images make technical documentation and README pages visually engaging. While markdown provides a native, simple format to link media files, adjusting image dimensions and alignments requires falling back to standard HTML tags. Plain text markup values readability, meaning its core syntax avoids heavy layout attributes.
This guide outlines how to embed image in markdown, configure alt descriptions, and align layout grids.
Jump to Section
1. Standard Image Syntax
The syntax to markdown add image objects is similar to link structures, prefixing the block with an exclamation mark (!):
Let us analyze the three components of this expression to understand how standard engines parse and generate the resulting HTML element:
When a markdown parser encounters this syntax, it compiles the plain text into an HTML image element:
<img src="/logo-white.svg" alt="Alternative descriptive text" title="Hover Tooltip Title" />
If the tooltip title is unnecessary for your document, omit the space and the quote strings entirely:
2. Alt Text SEO Best Practices
Writing proper alt text markdown is vital for two primary reasons: accessibility for visually impaired individuals relying on screen readers, and search engine image search optimization. Alt text informs crawlers about the content of your media.
To structure your alt descriptions for search engines and accessibility, verify that your text meets these instructions:
- Write description copy detailing the exact visual details of the image. Avoid assumptions.
- Exclude terms like "image of", "graphic showing", or "photo of". Parsers already recognize the media type.
- Ensure the text length is under 125 characters to prevent reading truncations in screen software.
- Incorporate target contextual keywords naturally without keyword stuffing or repeating syntax.
Here is a comparison list showing poor alt text structures versus optimized descriptions:
| Image Description Context | Poor Alt Text Structure | Optimized SEO Alt Text |
|---|---|---|
| Technical flow diagram |  |  |
| UI screenshot of editor |  |  |
| Company branding mark |  |  |
3. Resizing & Aligning (HTML Fallback)
Markdown is built for plain text writing. Because of this focus, there are no native syntax properties to resize image markdown layouts. To change image dimensions, write standard HTML image properties inside the document, which standard markdown engines render correctly.
Image Dimensions Adjustment
Replace the brackets and parentheses with an HTML image tag, utilizing standard width and height attributes:
<!-- Specifying image width in pixels --> <img src="/logo-white.svg" alt="Company Logo" width="250" /> <!-- Specifying height while preserving aspect ratio --> <img src="/logo-white.svg" alt="Company Logo" height="150" /> <!-- Using percentages for fluid styling layout --> <img src="/logo-white.svg" alt="Company Logo" style="width: 50%;" />
Some static processors or static compilers support custom suffix dimensions directly in the bracket declarations, though this format is not part of the standard markdown specification:
<!-- Custom processors format (e.g., Kramdown or Pandoc) -->
{: width="100px" height="50px"}Image Alignment Methods
Standard markdown anchors media to the left margin. If your design requires centered layouts or side floats, wrap your elements in HTML layout block containers.
To center-align your documentation images:
<div align="center"> <img src="/logo-white.svg" alt="Centered brand logo" width="300" /> </div>
For text wraps using floats, insert CSS attributes directly into the HTML tag properties:
<!-- Floating an image to the right with margins --> <img src="/logo-white.svg" alt="Right floating logo" style="float: right; margin-left: 15px;" width="150" />
4. Advanced Image Embedding
As your documents scale, you will encounter scenarios requiring advanced setups, such as linking images to destination web addresses, working with relative paths in monorepos, or embedding data inline.
Hyperlinked Media
Creating a clickable graphic requires nesting the image bracket group inside a standard link block. When users click the visual graphic, the browser navigates to the external resource target:
[](https://external-website.com)
This nested structure is parsed into active hyperlink wrapping tags, like this:
<a href="https://external-website.com"> <img src="/image-path.png" alt="Alt Text for Image" /> </a>
Relative File Paths vs. Remote URIs
When importing visual elements, determine whether you need local repository files or remote URLs. If you are preparing files for a Git project on GitHub, local files must use relative navigation indicators:
<!-- Reference image in the same folder -->  <!-- Reference image in a subfolder -->  <!-- Reference image one folder up --> 
Self-Contained Data URIs
If you want to keep your document inside a single file without external dependencies, convert your images to base64 encoding strings and reference them directly in the text payload:
5. Pitfalls & Common Mistakes
Syntax errors disrupt markdown parsers and lead to broken graphic squares. Be sure to troubleshoot these typical errors:
Missing Exclamation Marks
Forgetting the exclamation mark at the start converts your image definition block into a standard link anchor, hiding the image:
<!-- Error: renders as text link to image --> [Description](/logo.svg) <!-- Correct: compiles as image tag --> 
Incorrect Spacing Rules
Do not leave spaces between the brackets and parentheses. Any whitespace character breaks the token chain:
<!-- Error: parser breaks formatting --> ![Description] (/logo.svg) <!-- Correct --> 
Case Sensitivity on Target Files
Local systems like Windows are often case-insensitive when verifying files, but Linux hosts on web environments check exact strings. Ensure that the casing matches your file names:
<!-- File is saved as "screenshot.PNG" --> <!-- Error on web hosting -->  <!-- Correct --> 