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 ...
For further actions, you may consider blocking this person and/or reporting abuse
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.
There’s one huge caveat to this:
gitis 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.
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.
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.
If it is just a few things like a handful of screenshots, it goes in the top level.
Other times I'll use
docs/_media.I saw
.mediabefore but it ends up getting hidden in folder navigator, so I prefer_media.I might have used
_imagesbefore.If the docs folder is actually a docs site like Docsify or Jekyll, I'll use
assetsinstead of_media. And maybe separate outassets/img/andassets/cssto follow HTML conventions.I usually create a
.githubfolder within the repo at the root.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.
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.
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.
For the sake of preservation, it should all be hosted within the repo itself, perhaps in a
docsfolder at the rootProject's asset folder. Thanks for listing alternative approaches, though.
Make separate folder in the main root like
img/.I store
README.mdassets on the same repository with a separate directory. Same reason as @b4rtazI usually go with the docs folder approach myself...