When creating a GitHub repository README[1] you may want to have .jpg files, or even animated .gif files[2], to demonstrate things. Those can be added to the repository itself, but then everyone who clones or downloads the repository gets those files too, which may be many times larger than the actual code, so may be unnecessary bloat.
An images gist is created easily. It enables you to add images to your repositories' READMEs by adding full links to your gist’s images. The approach outlined is not one I have seen used, though it is effective in keeping the size of your repository(ies) slimmer. So, I thought it was worthwhile outlining it for others (and as a record for me to come back to too).
Your gist should have one .adoc (or .md, if you prefer). You will want it to appear as the “top” page (i.e., not have one of your images appear first) so the file name needs to sort alphabetically before any of the images’ file names. A good way to do that is to type a _ (LOW LINE, U+005F) at the start of the .adoc file name. In this gist, I created the file _How_To_Images_Gist.adoc. The content of the .adoc is not too important other than the heading, i.e., name it so that it is logically related to your repository(ies), and is easily identified when displayed in your gist’s home page.
You will probably want to make your gist a secret gist if all it will be doing is storing images for your repository(ies). Click the green button to Create secret gist.
|
💡
|
This does not impact accessing the images because secret gists are not actually very secret ― if someone knows the URI to your gist, they have access to view it. |
-
Get your gist’s “Clone via HTTPS” link:
Figure 1. ✓ Clone via HTTPS -
Using your git command line (or GUI) of choice, clone your gist. Using Git Bash on Windows, in my case it is:
git clone https://gist.github.com/9d4693e882f4ad4d75990e1a7576ce6f.git
-
Now copy whatever images you want added to the same directory as the .adoc file. That’s because gists cannot have any subdirectories, so these all need to be at the “root”.
-
Once copied, use
git add *and thengit commit -m "Adding images"to commit the image files. -
Finally,
git pushto GitHub (changing the{personal-access-token}to yours[3] and using your gist repo’s code, which you got from the "Clone via HTTPS" link). It should be like this:git push https://{personal-access-token}@gist.github.com/9d4693e882f4ad4d75990e1a7576ce6f.git, noting the “@”.
This should update your repository, with the images appearing below the .adoc file as individual files in your gist. Here’s the procedure above illustrated:
Now that the images are in your gist, they can be used wherever you like, including your GitHub repositories. It is simply a matter of right clicking the image, and copying the image’s link, like this:
This gist repository itself uses the images within it, but the principle is the same for any repository. So, the images in this gist could be used in any repository. For example, the first image used in this file is image::https://gist.github.com/kennypete/9d4693e882f4ad4d75990e1a7576ce6f/raw/9efe08af27327ba19b9df4977843212db4ebc902/creating_an_images_gist_01.jpg[creating_an_images_gist_01].[4]
, I think.
