Images in markdown as similar to a hyperlink, except it starts with an exclamation mark.

The following apply, as with standard links:

  • The target can point to a local file in the repo or a remote URL, as with standard links.
  • The text in the first part is alternative text shown while the image is loading (or if fails to load).
  • Optional text can be included at the end, to show on hover over.

General format

![ALT_TEXT](IMG_SRC)

![ALT_TEXT](IMG_SRC "HOVER TEXT")

Example code:

![My foo](foo.jpg)

![My foo](foo.jpg "A message about foo")

Notes

  • For local paths, the target is case sensitive. GitHub will show an error otherwise. Some IDE extensions are case-insensitive and so hide errors that will appear on GitHub.
  • You can include multiple images on one line. 
      ![foo](foo.png) ![bar](bar.png)

Linked images

Wrap an image a link so you navigate somewhere by clicking the image.

By default, an image tag alone will lead to a large version of the image (maybe not on static sites). But you can add a link around an image so clicking it goes somewhere.

[![ALT_TEXT](IMG_SRC)](CLICK_TARGET)

With whitespace for demonstration:

[ ![ALT_TEXT](IMG_SRC) ](CLICK_TARGET)

e.g.

[![Photo of me](/photo.png)](/about.html)

Building it up

Image:

![Alt text for broken image link](assets/logo.png)

Link:

[Alt text for broken link](httsp://example.com)

Image with link:

[![Alt text for broken image link](assets/logo.png)](https://example.com)

Note the link on the outside doesn’t have alt text anymore but the link still wraps the image.

Yes it is hard to read and edit but you get used to it as a pattern in Markdown.

Example of inline vs reference style

Inline-style

Example:

Code:

![Alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "This text shows on hover")

Result:

Code:

![Alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "This text shows on hover")

Reference-style

Code:

![Alt text][logo]

Some more text.

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "This text shows on hover"

There is a logo above but this element but it is not visible in the rendered HTML.

Result:

Alt text

Some more text.

There is a logo above but this element but it is not visible in the rendered HTML.

Plain HTML

For more control, you can use HTML for your images.

<img src="foo.jpg">

Here we make the image clickable, to emulate what a markdown image does.

<a href="https://example.com/foo/">
    <img src="https://example.com/bar.png">
</a>

Styled HTML

Resize and center an image using HTML attributes.

GitHub also sets max-width to 100% on the CSS when rendering the page, so that means your image can take up a lot of space.

A good way to do this is set the exact height - letting the pixel width change based on desktop or mobile. Fine-tune the value per image.

<p align="center">
    <img height="300px" src="foo.png">
</p>

Or use a relative width value:

  • width="80%"

Notes:

  • Centering and resizing as above cannot be achieved by setting CSS (inline or in a style tag) on GitHub, so you must update attributes of the tags. The align attribute works for now in HTML5 but will eventually stop as it is deprecated.
  • The resizing above works for HTML tags in markdown, but resizing cannot be done for markdown image. At least in GitHub-flavored implementation of markdown - some other systems support resizing e.g. ![Alt](img.jpg =60x50).
  • The image will be hyperlinked to the full size version of the image, unless you add an anchor tag.

Add elements

You can use other elements in the outer tag.

In the case of a badge image as a second element, that will only be centered if the outer element is a div and not a p. I don’t know why.

Example:

<div align="center">
    <a href="https://michaelcurrin.github.io/unicron/">
        <img width="250" src="docs/_media/logo.png" alt="Unicron logo" />

![GitHub Pages site](https://img.shields.io/badge/docs-GitHub_Pages-f967f9?style=for-the-badge)
    </a>

</div>

Note the lack of a space before the closing a tag otherwise that is just indented text. Or it has to have no indentation.

The badge could also be converted to an img tag for consistency. Then a line break is needed to keep the images on separate lines.

<div align="center">
    <a href="https://michaelcurrin.github.io/unicron/">
        <img width="250" src="docs/_media/logo.png" alt="Unicron logo">
        <br>
        <img src="https://img.shields.io/badge/docs-GitHub_Pages-f967f9?style=for-the-badge" alt="GitHub Pages site"/>
    </a>
</div>

SVGs

Format:

![Alt text](foo.svg)

![Alt text](https://example.com/foo.svg)

Example

Code::

![Alt text](https://placeholder.pics/svg/200x60/DEDEDE/555555/Sample%20SVG)

Result

Alt text

Using raw.githubusercontent.com

If you reference an image on GitHub through the Raw button, you get a link for raw.githubusercontent.com. You must add this to the URL to avoid getting an error: ?sanitize=true.

Example of the above. This could be Markdown too, but with HTML to set the width.

<img width="100px"
     src="https://raw.githubusercontent.com/graphql/graphql-spec/master/resources/GraphQL%20Logo.svg?sanitize=true" />

Image link from Wikipedia icon here.

If you use a different domains below, though you do not need the sanitize parameter.

Using github.io

An asset hosted on a GitHub Pages site.

![Alt text](https://potherca-blog.github.io/StackOverflow/question.13808020.include-an-svg-hosted-on-github-in-markdown/controllers_brief.svg)

Alt text