Where do you store GitHub README.md assets?

GitHub README.md is the front page of your project. You want to make it visually appealing, as it's the first thing the visitor checks in order to get a grasp of what the project is about.

Where do you store the images and other media assets (like screenshots, gifs, etc) of README.md? Including them directly in the project's assets folder seems to be odd as they are not directly related to the project itself.

Some of the approaches I've heard include:

• Hosting them on External CDN like Imgur
• Creating a new dummy issue and upload them there
• Using a separate assets branch

What is your favorite workaround for this?

Comments

[b4rtaz]

I think the best place is the repository. When someone downloads your repository he has everything what he needs to read all content correctly. The second thing is a backup, every copy of your repository is a whole backup of your project. And third, I want to maintain one repository instead three projects/resources.

[Austin S. Hemmelgarn]

There’s one huge caveat to this: git is horrible at storing binary data. With text, it can store efficient diffs instead of whole files, but for binary files it has to store the whole file each time it changes. This, in turn, makes clone and pull times longer, makes the repo bigger (I’ve seen cases of repos with commits in the low thousands and only a few hundred kB of code that were nonetheless hundreds of MB in size simply because of trying to version frequently changing binary files), and also doesn’t really give you much in the way of useful info for versioning (yes, you can grab old versions, but you can’t inspect differences).

Yes, if it’s stuff like (uncompressed) SVG images then it does make some sense, but a lot of things people seem to like to put into README files are binaries, and they’re often big (especially screenshots these days).

If you really want to do this, git-lfs is really the only sane way to handle it.

[b4rtaz]

The question is what do you want attach to README. I think, the most popular cases are screenshot images, a logo file, etc. In this case I think the repository is a rational place. But if you want to store many images, for example, for the documentation needs or .psd files ;) I think you need to put your files outside the repo.

I look at that problem like a the ratio of the work cost to impact to the future. If I knew that my files are not often changed, then I would put them to the repository. In the opposite situation (bad long term impact) I would put them outside.

Of course in this strategy the key is the good sense. And this you can only gain by a bigger experience.

[ronca85]

Hello,

I've seen people use github issues to host screenshots. This is cool if you don't want to bloat your project repo with stuff that is only used for documentation.

In your repo go to Issues tab, click "New Issue" button and drag and drop the image into the text edit area. I don't think there's a different way to do this apart from drag and drop but this works. This will generate an url which you want to copy and use in the readme.

You don't want to submit this new issue, just want to exploit the system to host your image. Whenever you see images in readmes and they link to urls that look like this user-images.githubusercontent.com/... they have been uploaded using this method.

[Michael Currin]

If it is just a few things like a handful of screenshots, it goes in the top level.

README.md
sample-1.png
sample-2.png

Other times I'll use docs/_media.

docs/
  _media
    sample-1.png
    sample-2.png
  README.md
README.md

I saw .media before but it ends up getting hidden in folder navigator, so I prefer _media.
I might have used _images before.

If the docs folder is actually a docs site like Docsify or Jekyll, I'll use assets instead of _media. And maybe separate out assets/img/ and assets/css to follow HTML conventions.

[Christian Menezes]

I usually create a .github folder within the repo at the root.

[Bill Raymond]

I’m totally saying this knowing so very little knowledge, but you might want to reconsider this approach. With GitHub actions now living under the .github folder, they may decide to expand on the use of that folder in the future, making it their little world to add more features your repo can take advantage of. Putting your docs under that folder may be fine forever, but just thinking out loud you might want to reconsider the specific folder you use.

[Michael Currin]

Agree. It already has a purpose.

Also, reading docs with images in them works outside of GitHub, such as in a markdown viewer in your IDE.

[Junxiao Shi]

The only asset in my README is the project logo. It's a handwritten SVG in docs/logo.svg.

I do not include screenshots or animations in the README. These are published on my blog. I funnel traffic to my blog using this method.

[Shane McGowan]

For the sake of preservation, it should all be hosted within the repo itself, perhaps in a docs folder at the root

[Pacharapol Withayasakpunt]

Project's asset folder. Thanks for listing alternative approaches, though.

[Louis Low]

I store README.md assets on the same repository with a separate directory. Same reason as @b4rtaz

[Swastik Baranwal]

Make separate folder in the main root like img/.

[Johnny Tordgeman]

I usually go with the docs folder approach myself...