Add images to README.md on GitHub

Question

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?

Answer 1

I need to include some images in my README File. I don't know how to do that.

I created a small wizard that allows you to create and customize simple image galleries for your GitHub repository's readme: See ReadmeGalleryCreatorForGitHub.

The wizard takes advantage of the fact that GitHub allows img tags to occur in the README.md. Also, the wizard makes use of the popular trick of uploading images to GitHub by drag'n'dropping them in the issue area (as already mentioned in one of the answers in this thread).

Answer 2

In case you need to upload some pictures for documentation, a nice approach is to use git-lfs. Asuming that you have installed the git-lfs follow these steps:

1. Intialize git lfs for your each image type:

   git lfs *.png
   git lfs *.svg
   git lfs *.gif
   git lfs *.jpg
   git lfs *.jpeg
   

2. Create a folder that will be used as image location eg. doc. On GNU/Linux and Unix based systems this can be done via:

   cd project_folder
   mkdir doc
   git add doc
   

3. Copy paste any images into doc folder. Afterwards add them via git add command.

4. Commit and push.

5. The images are publicly available in the following url:

   https://media.githubusercontent.com/media/^github_username^/^repo^/^branch^/^image_location in the repo^

Where: * ^github_username^ is the username in github (you can find it in the profile page) * ^repo_name^ is the repository name * ^branch^ is the repository branch where the image is uploaded * ^image_location in the repo^ is the location including the folder that the image is stored.

Also you can upload the image first then visit the location in your projects github page and navigate through until you find the image then press the download button and then copy-paste the url from the browser's address bar.

Look this from my project as reference.

Then you can use the url to include them using the markdown syntax mentioned above:

![some alternate text that describes the image](^github generated url from git lfs^)

Eg: Let us suppose we use this photo Then you can use the markdown syntax:

![In what order to compile the files](https://media.githubusercontent.com/media/pc-magas/myFirstEnclave/master/doc/SGX%20Compile%20workflow.png)

Answer 3

I am just extending or adding an example to the already accepted answer.

Once you have put the image on your Github repo.

Then:

• Open the corresponding Github repo on your browser.
• Navigate to the target image file Then just open the image in a new tab.
• Copy the url
• And finally insert the url to the following pattern ![alt text](https://raw.githubusercontent.com/username/projectname/branch/path/to/img.png)

On my case it is

![In a single picture](https://raw.githubusercontent.com/shadmazumder/Xcode/master/InOnePicture.png)

Where

• shadmazumder is my username
• Xcode is the projectname
• master is the branch
• InOnePicture.png is the image, On my case InOnePicture.png is in the root directory.

Answer 4

I wanted to update this using ZenHub, since GitHub and ZenHub have changed their graphical layouts.

If you install ZenHub and allow access to your GitHub, then you can navigate to the ZenHub tab once in your repo and open a new issue.

This is an updated version of Ahmad Amji's YouTube video posting.

Step 1:

Step 2: From there you can open an attachment.

Step 3: And then from there you can use the link generated automatically. This way you don't have to bother with creating a new repo just for images.

Then use the standard MarkDown syntax with the URL provided.

Step 4

![alt text](image URL from ZenHub issue)

Step 5 Don't forget to close the issue draft and not actually submit it. The image URL should still work properly!

Answer 5

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 needed below.

Construct a "permalink" to this revision of the image, and wrap it in Markdown:

![Cat](https://raw.githubusercontent.com/{user}/{repo}/{sha}/cat.png)

e.g.

![Cat](https://raw.githubusercontent.com/paulmelnikow/zsh-startup-timer/3923c60fc66d4223ccf063d169ccf2ff167b1270/cat.png)

To always show the latest image on the assets branch, use assets in place of the sha:

![Cat](https://raw.githubusercontent.com/{user}/{repo}/assets/cat.png)

Answer 6

It's much simpler than that.

Just upload your image to the repository root, and link to the filename without any path, like so:

![Screenshot](screenshot.png)