How to add screenshot to READMEs in github repository?

Question

Is it possible to place a screenshot in README file in a GitHub repository? What's the syntax?

The correct solution to this is to use relative references, per this answer http://stackoverflow.com/a/11916467/1633251 (see the comment with the link to a new github doc on how to do this). The short answer is to use `[Read more words!](docs/more_words.md)` — David H, Feb 11 '14 at 19:11
Most solutions propose to point to the repo itself. What about if you want to avoid binaries in the repo (even in a separated branch, as proposed) and you want to store it in an external place? Any good practices? A gist maybe (IDK if gist can be binary or just text)? creating another repo "myproject-assets" for the project "myproject"? Any external popular image-place similar to the de-facto standard of youtube for uploading videos? — Xavi Montero, Nov 11 '14 at 16:14
Possible duplicate of [Add images to README.md on GitHub](http://stackoverflow.com/questions/14494747/add-images-to-readme-md-on-github) — ashokramcse, Nov 09 '16 at 07:01
March 2021: simple drag&drop: See [my answer below](https://stackoverflow.com/a/66465892/6309) — VonC, Mar 03 '21 at 22:28
Not an answer.. just a suggestion https://dillinger.io/ this online makedown editor has good options — Karthikeyan, Mar 05 '22 at 13:36

Paul · Accepted Answer · 2019-06-26T11:35:53.820

993

If you use Markdown (README.md):

Provided that you have the image in your repo, you can use a relative URL:

![Alt text](/relative/path/to/img.jpg?raw=true "Optional Title")

If you need to embed an image that's hosted elsewhere, you can use a full URL

![Alt text](http://full/path/to/img.jpg "Optional title")

GitHub recommend that you use relative links with the ?raw=true parameter to ensure forked repos point correctly.

The raw=true parameter is there in order to ensure the image you link to, will be rendered as is. That means that only the image will be linked to, not the whole GitHub interface for that respective file. See this comment for more details.

Check out an example: https://raw.github.com/altercation/solarized/master/README.md

If you use SVGs then you'll need to set the sanitize attribute to true as well: ?raw=true&sanitize=true. (Thanks @EliSherer)

Also, the documentation on relative links in README files: https://help.github.com/articles/relative-links-in-readmes

And of course the markdown docs: http://daringfireball.net/projects/markdown/syntax

Additionally, if you create a new branch screenshots to store the images you can avoid them being in the master working tree

You can then embed them using:

![Alt text](/../<branch name>/path/to/image.png?raw=true "Optional Title")

edited Jun 26 '19 at 11:35

answered Apr 17 '12 at 10:22

Paul

20,883
7
57
74

1

Well, I added the official docs on relative links, but I'm unable to find some repo that uses them, if you have suggestions, I'll be happy to help since the whole point is helping more people, not staying in the scope (my mistake here). – Paul Jun 20 '13 at 18:43
2

@Paul , here's an example repository doing just that! https://github.com/Tarrasch/zsh-bd – Tarrasch Sep 02 '13 at 22:23
You can also link the image to somewhere other than the raw image file using the following syntax: `[![Alt text](/path/to/img.jpg?raw=true)][http://example.com/]` – sstur Sep 15 '14 at 07:26
5

https://github.com/altercation/solarized is the rendered version of the example above, in case that helps anyone. – Jul 09 '15 at 12:57
Is it possible to put an image, that's actually a link? – android developer Apr 01 '16 at 09:25
Yes, you can use a full URL too, if that's what you mean. Check the answer please. – Paul Apr 01 '16 at 09:27
The example doesn't seem to have relative links anymore. – chesterbr May 07 '16 at 16:16
I have done it like thousand time but still I forgot syntax every time. – Hitesh Sahu Feb 26 '17 at 05:05
7

When you say `/relative/path/to/img.jpg`, isn't that an absolute path due to the leading slash? – jww Jul 15 '17 at 05:50
what does mean by `Alt text`? – alhelal Oct 13 '17 at 04:32
Does it supports `.pdf`? – alhelal Oct 13 '17 at 04:35
If you store the image in another branch, the proposed solution /..//path/to/image.png works only with the GitHub README, and not when working with the README file locally. Please see [this question](https://stackoverflow.com/questions/49670565/display-github-readme-screenshot-stored-in-a-different-branch-both-on-github-an) – TechAurelian Apr 05 '18 at 13:28
It looks like your example site stopped using relative links. – Robert Hafner Apr 15 '18 at 20:31
Note that `?raw=true` does not work for SVG! Just remove that parameter and it'll work. – Navin May 01 '18 at 04:03
@Paul I have implemented your solution and it's worked like a charm. But I am facing one issue, gif is playing only once. While in my local machine it is playing on repeat mode. I don't know why GitHub plays it only once. Any Help is appreciated! Thank you – iGatiTech Jul 19 '18 at 05:37
@Paul "GitHub recommend that you use relative links with the ?raw=true parameter to ensure forked repos point correctly." Is this still relevant/valid? I could not find it in the GitHub documentation. – kelvin Dec 31 '18 at 15:35
1

@kelvin, the `raw=true` parameter is there in order to render the image the GitHub path points to, not the GitHub interface. Try and see the difference: https://github.com/altercation/solarized/blob/master/img/screen-html-dark-th.png vs https://github.com/altercation/solarized/blob/master/img/screen-html-dark-th.png?raw=true. The first URL will show you the GitHub interface and the image, while the second will only show you the image. The relative links are still useful when cloning/forking repos, so yes you should use relative paths with that parameter, but they are two different concepts. – Paul Jan 03 '19 at 09:01
1

@gati, I am sorry, I do not have any idea on your issue. – Paul Jan 03 '19 at 09:02
2

For SVG to work add sanitize (i.e. `?raw=true&sanitize=true`) – EliSherer Jun 21 '19 at 18:54
Excellent concision, you just taught me about the raw=true param. For future travelers, my issue was related to how Google Cloud Storage actually serves its images. To make it work I had to grab the rendered long-url from Google, see my answer below. – Jason R Stevens CFA Jan 03 '20 at 17:37
@Paul do you know how resize the image – johnson May 18 '23 at 06:09

score 86 · Answer 2 · edited Mar 12 '23 at 00:03

86

Even though there is already an accepted answer I would like to add another way to upload images to readme on GitHub.

You need to create issue in your repo
Drag and drop in the comment area your image
After link for the image is generated insert it to your readme

More details you can find here

edited Mar 12 '23 at 00:03

William Isted

11,641
4
30
45

answered Jul 21 '15 at 03:15

8

I'm interested how long images loaded this way will live. Does github perform some images cleanup? Like, "if this image not referenced from any github issue, I can safely remove it"... – artin Aug 07 '17 at 01:09
2

@Artin probably only when the issue is deleted completely. Closed issues stick around forever as they serve a very important role in documentation and debugging – andrhamm May 25 '18 at 17:24
1

The hyperlink provided in this answer seems fishy – EMT Feb 24 '23 at 08:46
1

@EMT The domain appears to have changed over the years and is expired / dormant. I've updated the link to an archive.org mirror. Thanks for pointing it out. – William Isted Mar 12 '23 at 00:06

score 56 · Answer 3 · answered Oct 21 '12 at 11:47

56

I found that the path to the image in my repo did not suffice, I had to link to the image on the raw.github.com subdomain.

URL format https://raw.github.com/{USERNAME}/{REPOSITORY}/{BRANCH}/{PATH}

Markdown example ![Settings Window](https://raw.github.com/ryanmaxwell/iArrived/master/Screenshots/Settings.png)

answered Oct 21 '12 at 11:47

Ryan

5,416
1
39
36

5

Downvoting this because of @sorens comment on the accepted answer. It's bad to specify absolute bath since it won't work well on forked repositories. (Or if you rename your repo, or if github changes domain name, etc. etc.) – Linus Unnebäck Nov 14 '13 at 21:24
10

@LinusUnnebäck: There's one good reason to use absolute paths imho: If the readme.md is used in other places as well, for example, as a Doxygen main-page. Relative links won't work then. – Ela782 Aug 30 '15 at 00:57
2

@Ela782 although, on a further note, that *ought* not to be an issue for software that's ripping README files *specifically from GitHub*; such software should know to resolve relative URLs properly. [npm does](https://github.com/npm/npm-www/issues/517), for example. – Mark Amery Jan 24 '16 at 19:52
how to link to the image on the `raw.github.com` subdomain ? where to upload the image file ? – Saif Aug 11 '17 at 13:59
@Saif raw.github.com is just a reflection of what is committed to your github repository. Just commit the image to your repository and follow the URL format specified. – Oct 03 '17 at 06:00
@LinusUnnebäck That's exactly why I'm trying to use relative URLs. However, I'm storing the images in an `assets` branch, and I'm having issues to make it work with both the GitHub README, and with the README file locally. Please see [this question](https://stackoverflow.com/questions/49670565/display-github-readme-screenshot-stored-in-a-different-branch-both-on-github-an) – TechAurelian Apr 05 '18 at 13:34

score 53 · Answer 4 · edited Jun 20 '20 at 10:20

53

JUNE 3, 2020 : WORKING ANSWER-

Upload your image to postimage.org
Copy Github-Markdown-Url after uploading Image
Insert in your ReadMe

edited Jun 20 '20 at 10:20

Shobhakar Tiwari

7,862
4
36
71

answered Nov 18 '16 at 19:33

diju

647
5
2

4

You are the only one whose answer was useful to me – Cypher May 27 '20 at 12:22
6

It's a fine answer, but just be aware you're depending on that service to exist forever. It makes no guarantees about not disappearing one day. Neither does GitHub, but enough important projects and people depend on it that I feel safe that I'd at least be provided backups / dumps before it went down. Also, I don't know what its terms and conditions say, but again, because a lot more people would have pored over GitHub's T&C, I trust it more. – Andrew Cheong Jul 12 '20 at 01:40
...and also if the image is on GitHub, the image and the readme will disapear together. – vidstige Mar 02 '21 at 20:41
@AndrewCheong for any mission critical assets, reliance on a single third party is never a good idea. GitHub or any other service should NOT be _relied_ on to provide disaster recovery backups. Ultimately the assets should be protected through multiple backup options. At least with `git` backing up to multiple stores is pretty simple. – ocodo Aug 13 '22 at 02:18
GitHub no longer allows links from postimage. If you follow this procedure, you'll receive this error in the JavaScript console: `Refused to load the image 'https://i.postimg.cc/...' because it violates the following Content Security Policy directive: "img-src 'self' data: github.githubassets.com media.githubusercontent.com camo.githubusercontent.com identicons.github.com avatars.githubusercontent.com github-cloud.s3.amazonaws.com objects.githubusercontent.com objects-origin.githubusercontent.com secured-user-images.githubusercontent.com/ user-images.githubusercontent.com/ ...` – nfv May 20 '23 at 00:03

score 25 · Answer 5 · answered May 26 '13 at 20:09

25

One line below should be what you looking for

if your file is in repository

![ScreenShot](https://raw.github.com/{username}/{repository}/{branch}/{path})

if your file is in other external url

![ScreenShot](https://{url})

answered May 26 '13 at 20:09

mmcorrelo

946
1
10
10

2

suggest using the relative link of the image file, see [Relative links in READMEs - Github Help](https://help.github.com/articles/relative-links-in-readmes) – shaobin0604 Mar 22 '14 at 15:38
2

-1 for the reason given by @shaobin0604; the official docs recommend using relative links when linking to a file in your own repo, so that the link points to the right place when forked. – Mark Amery Jan 24 '16 at 19:49

edelans · Answer 6 · 2016-02-03T13:52:59.640

The markdown syntax for displaying images is indeed:

![image](https://{url})

BUT: How to provide the url ?

You probably do not want to clutter your repo with screenshots, they have nothing to do with code
you might not want either to deal with the hassle of making your image available on the web... (upload it to a server... ).

So... you can use this awesome trick to make github host your image file. TDLR:

create an issue on the issue list of your repo
drag and drop your screenshot on this issue
copy the markdown code that github has just created for you to display your image
paste it on your readme (or wherever you want)

http://solutionoptimist.com/2013/12/28/awesome-github-tricks/

score 16 · Answer 7 · answered Jan 30 '18 at 11:33

16

Much simpler than adding URL Just upload an image to the same repository, like:

![Screenshot](screenshot.png)

answered Jan 30 '18 at 11:33

Taymour Niazi

171
1
5

not able to resize the image using `![Screenshot](screenshot.png)` – johnson May 18 '23 at 06:36

score 13 · Answer 8 · answered Mar 08 '18 at 17:16

13

add this to README

<div align="center">
    <img src="/screenshots/screen1.jpg" width="400px"</img> 
</div>

answered Mar 08 '18 at 17:16

Dan Alboteanu

9,404
1
52
40

score 12 · Answer 9 · answered Mar 03 '21 at 22:28

From March 2021, this is now supported:

Attaching files to markdown files

You can now attach files, including images, to markdown files while you're editing them in the web.

This works just like file attachments in issues and pull requests and supports the same file types.

Just drag and drag, click and select, or paste.

Note: If you add an image to a markdown file, anyone can view the anonymized image URL without authentication, even if the markdown file is in a private repository.
To keep images private, serve them from a private network or server that requires authentication. For more information on anonymized URLs see "About anonymized image URLs".

@NeerajaGandla once imported, check https://gist.github.com/uupaa/f77d2bcf4dc7a294d109 or https://gist.github.com/MichaelPolla/a65ac84286ab523603e64549f9850223 — VonC, Nov 24 '21 at 10:51

score 7 · Answer 10 · answered Aug 17 '17 at 14:44

Method 1->Markdown way

![Alt Text](https://raw.github.com/{USERNAME}/{REPOSITORY}/{BRANCH}/{PATH})

Method 2->HTML way

<img src="https://link(format same as above)" width="100" height="100"/>

or

<img src="https://link" style=" width:100px ; height:100px " />

Note-> If you don't want to style your image i.e resize remove the style part

score 4 · Answer 11 · answered Sep 09 '21 at 12:57

For me, the relative path worked out very well.

How I did this: In my current md file where I wanted to use a picture from another directory, I used a relative path like this - consider following points.

md file loc: base dir -> _post -> current_file.md

& picture file loc which I wanted to use: base dir -> _asset -> picture_to_use.jpeg

What the statement I used was on current_file.md file:

![your-pic-caption-name](../_asset/picture_to_use.jpeg)

Note - before this, I was using direct _asset but Ideally, it so starts from ../_asset/and-so-no

reference - https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-readmes

score 3 · Answer 12 · answered Oct 06 '20 at 01:10

Add ![ScreenShot](screenshot.png) in the readme markdown as mentioned by many above. Replace screenshot.png with the name of the image you uploaded in your repository.

But here is a newbie tip when you upload the image (as I made this mistake myself):

ensure that your image name does not contain spaces. My original image was saved as "Screenshot day month year id.png". If you don't change the name to something like contentofimage.png, it won't appear as an image in your readme file.

Easiest method by far! I was just about to make this entry myself when I read down far enough to see this excellent answer. They only let me upvote once. — jim, Jan 14 '22 at 12:22

score 3 · Answer 13 · edited Mar 22 '23 at 15:08

3

Please follow these steps: this worked for me

Create a new issue on GitHub.
Drag and drop an image onto the comment field or upload a photo.
Wait for the upload process to finish.
Copy the URL and use it in your Markdown files on GitHub (use that generated URL in your repository's readme).

edited Mar 22 '23 at 15:08

Monu Rohilla

1,311
5
20

answered Jan 23 '22 at 07:18

Rohullah Nabavi

82
6

1

Best to just add it to your repo, not indirectly using an upload from an issue. This way it can be versioned and changed more easily over time as well. – hrbdg Jun 11 '22 at 12:17

Jason R Stevens CFA · Answer 14 · 2020-03-25T02:59:02.283

I googled a few similar questions and did not see any answers with my problem and its quite simple/easy solution.

Google Cloud Storage - a slightly different approach to images in READMEs

Here goes: like the OP, I wanted an image in my Github README, and, knowing the Markdown syntax for doing so, typed it in:

![My Image](https://storage.cloud.google.com/${MY_BUCKET}/${MY_IMAGE}

You need to complete the actual substitutions above (e.g. MY_IMAGE=image.jpg) for this to work.

But, wait...failure--there's no actual rendered photo! And the link is exactly as given by Google Storage!

Github `camo` - Anonymous Images

Github hosts your images anonymously, yay! However, this presents an issue for Google storage assets. You need to get the generated url from your Google Cloud Console.

I'm sure there's a smoother way, however, simply visit your given URL endpoint and copy the long URL. Details:

Instructions

Visit your storage console: https://console.cloud.google.com/storage/browser/${MY_BUCKET}?project=${MY_PROJECT}
Click on the image you'd like to display in Github (this brings up the "Object Details" page)
Copy pasta that URL (the one starting with https not gs) into a new browser tab/window
Copy pasta the new generated URL -- it should be longer -- from your new browser tab/window into your Github README file

Hopefully this helps speed up and clarify this issue for anyone else.

FYI -- It appears something is changing on the Google or Github side of things. I've had some images in READMEs failing via this method, and some working as of afternoon March 28, 2020. YMMV here! — Jason R Stevens CFA, Mar 28 '20 at 23:38

score 1 · Answer 15 · edited Apr 02 '18 at 16:54

First, create a directory(folder) in the root of your local repo that will contain the screenshots you want added. Let’s call the name of this directory screenshots. Place the images (JPEG, PNG, GIF,` etc) you want to add into this directory.

Android Studio Workspace Screenshot

Secondly, you need to add a link to each image into your README. So, if I have images named 1_ArtistsActivity.png and 2_AlbumsActivity.png in my screenshots directory, I will add their links like so:

 <img src="screenshots/1_ArtistsActivity.png" height="400" alt="Screenshot"/> <img src=“screenshots/2_AlbumsActivity.png" height="400" alt="Screenshot"/>

If you want each screenshot on a separate line, write their links on separate lines. However, it’s better if you write all the links in one line, separated by space only. It might actually not look too good but by doing so GitHub automatically arranges them for you.

Finally, commit your changes and push it!

score 0 · Answer 16 · edited Nov 27 '16 at 22:43

0

To me the best way is -

Create an new issue with that repository on github and then upload the file in gif format.To convert video files into gif format you can use this website http://www.online-convert.com/
Submit the newly created issue.
Copy the address of the uploaded file
Finally in your README file put ![demo](COPIED ADDRESS)

Hope this will help .

edited Nov 27 '16 at 22:43

Robbie

17,605
4
35
72

answered Nov 27 '16 at 22:19

Asifur Rahman

17
3

How is it different from https://stackoverflow.com/a/32252663/1570104 ? – edelans May 18 '20 at 11:17

score 0 · Answer 17 · answered Dec 23 '19 at 11:58

0

Add image in repository from upload file option then in README file

![Alt text]("enter image url of repositoryhere")

answered Dec 23 '19 at 11:58

Marium Jawed

391
4
9

score -1 · Answer 18 · answered Oct 22 '21 at 08:07

-1

Create a New issue by clicking on the green button in the upper right corner. Take a screenshot of whatever you need and paste it into the issue message (CMD+V on Mac or CTR+V on Windows).

answered Oct 22 '21 at 08:07

Pooja Pathak

9
1

Junaed · Answer 19 · 2022-10-20T14:54:56.657

My image had space in the name, e.g. Pasted image 20221006123035.png, and that was causing a problem from me, and I lost some time fixing it. If someone has the same issue, then here are the steps

I uploaded the image via upload option
Then clicked on the image in the file browsing UI of the website.
The image is opened in the browser. From the browser's URL I copied the url of the image. You can copy the whole path, or relative to your .md file
Now insert that link to the .md file like ![overview](Pasted%20image%2020221006123035.png)

Mick Cullen · Answer 20 · 2015-05-18T11:38:13.637

-5

With the images located in /screen-shots directory. The outer <div> allows the images to be positioned. Padding is achieved using <img width="desired-padding" height="0">.

<div align="center">
        <img width="45%" src="screen-shots/about.PNG" alt="About screen" title="About screen"</img>
        <img height="0" width="8px">
        <img width="45%" src="screen-shots/list.PNG" alt="List screen" title="List screen"></img>
</div>

edited May 18 '15 at 11:38

answered Sep 24 '14 at 11:34

Mick Cullen

9,214
3
21
17

1

For the life of me I couldn't figure out to center an image in the README - which your answer contains, so thanks! – Cody Reichert Oct 30 '15 at 18:12
I found this answer helpful since it enables you to set the dimensions of the image – Stanley May 17 '20 at 10:58

How to add screenshot to READMEs in github repository?

20 Answers20

Attaching files to markdown files

For me, the relative path worked out very well.

Google Cloud Storage - a slightly different approach to images in READMEs

Github `camo` - Anonymous Images

Instructions

Linked

How to add screenshot to READMEs in github repository?

20 Answers20

Attaching files to markdown files

For me, the relative path worked out very well.

Google Cloud Storage - a slightly different approach to images in READMEs

Github camo - Anonymous Images

Instructions

Linked

Github `camo` - Anonymous Images