DEV Community

loading...
Cover image for Where do you store GitHub README.md assets?

Where do you store GitHub README.md assets?

madza profile image Madza ・1 min read

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?

Discussion

pic
Editor guide
Collapse
b4rtaz profile image
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.

Collapse
ahferroin7 profile image
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.

Collapse
b4rtaz profile image
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.

Collapse
ronca85 profile image
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.

Collapse
michaelcurrin profile image
Mike

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
Enter fullscreen mode Exit fullscreen mode

Other times I'll use docs/_media.

docs/
  _media
    sample-1.png
    sample-2.png
  README.md
README.md
Enter fullscreen mode Exit fullscreen mode

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.

Collapse
christianmoliveira profile image
Christian Menezes

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

Collapse
billraymond profile image
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.

Collapse
michaelcurrin profile image
Mike

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.

Collapse
yoursunny profile image
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.

Collapse
shane profile image
shane

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

Collapse
loouislow profile image
Loouis Low

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

Collapse
delta456 profile image
Swastik Baranwal

Make separate folder in the main root like img/.

Collapse
patarapolw profile image
Pacharapol Withayasakpunt

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

Collapse
pxjohnny profile image
Johnny Tordgeman

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