Add images to README.md on GitHub
Recently I joined GitHub. I hosted some projects there.
I need to include some images in my README File. I don't know how to do that.
I searched about this, but all I got was some links which tell me to "host images on web and specify the image path in README.md file".
Is there any way to do this without hosting the images on any third-party web hosting services?
Try this markdown:
I think you can link directly to the raw version of an image if it's stored in your repository. i.e.
Read more... Read less...
You can also use relative paths like
![Alt text](relative/path/to/img.jpg?raw=true "Title")
You can also add images with simple HTML tags:
<p align="center"> <img src="your_relative_path_here" width="350" title="hover text"> <img src="your_relative_path_here_number_2_large_name" width="350" alt="accessibility text"> </p>
Many of the posted solutions are incomplete or not to my taste.
- An external CDN like imgur adds another tool to the chain. Meh.
- Creating a dummy issue in the issue tracker is a hack. It creates clutter and confuses users. It's a pain to migrate this solution to a fork, or off GitHub.
- Using the gh-pages branch makes the URLs brittle. Another person working on the project maintaining the gh-page may not know something external depends on the path to these images. The gh-pages branch has a particular behavior on GitHub which is not necessary for hosting CDN images.
- Tracking assets in version control is a good thing. As a project grows and changes it's a more sustainable way to manage and track changes by multiple users.
- If an image applies to a specific revision of the software, it may be preferable to link an immutable image. That way, if the image is later updated to reflect changes to the software, anyone reading that revision's readme will find the correct image.
My preferred solution, inspired by this gist, is to use an assets branch with permalinks to specific revisions.
git checkout --orphan assets git reset --hard cp /path/to/cat.png . git add . git commit -m 'Added cat picture' git push -u origin assets git rev-parse HEAD # Print the SHA, which is optional, you'll see below.
Construct a "permalink" to this revision of the image, and wrap it in Markdown.
Looking up the commit SHA by hand is inconvenient, however, so as a shortcut press Y to a permalink to a file in a specific commit as this help.github page says.
To always show the latest image on the assets branch, use the blob URL:
(From the same GitHub help page File views show the latest version on a branch)