If you have a few years of experience in the DevOps ecosystem, and you're interested in sharing that experience with the community, have a look at our Contribution Guidelines.
1. Overview
When working on a GitHub project, we need to create a well-crafted README.md file. This file is often the first thing visitors see in a GitHub repository. Moreover, the README.md file is a guide that provides us with a detailed project description. Typically, it includes instructions on installation, usage, and other relevant details.
While README.md files primarily consist of text, there are instances where adding graphical images or illustrations becomes necessary. However, adding images into a Markdown-formatted README.md file can be tricky.
In this tutorial, we’ll explore different ways to add images to the GitHub README.md file, including externally hosted images.
2. Adding Images to README.md on GitHub
We can add images to the README.md file using the relative URL or by dragging and dropping to the file editor. We can also embed externally hosted images by defining their full path.
Let’s explore all the different ways to add images to a README.md file.
2.1. Drag and Drop the Image Directly to README.md
The simplest way to add an image to a README.md file is by directly uploading it to the README.md file itself.
To add an image, we need to click the Edit button in front of the README.md file. After that, we can drag the image directly from our PC and drop it inside the editor.
Next, GitHub will upload the image to our repository and display its Markdown code:
Finally, we can click Commit Changes or select the Preview option to check how the image looks now.
2.2. Using Relative Path
Another way to add images to the README.md file is to upload them to the root repository or create a separate folder for them. After uploading images to the GitHub repository, we could then add them to a README.md file using their relative path link.
Next, let’s see how to add an image using Markdown syntax:
We make sure to use relative links with ?raw=true for proper rendering, especially for forked repositories. Additionally, we need to avoid spaces in image filenames.
2.3. Add Externally Hosted Image
We can also add images from the web to the Markdown README.md file. This method allows us to reference images stored on other websites, cloud storage, or content delivery networks (CDNs). Moreover, it’s similar to adding images like we have on our own computer, but instead of a file path, we’ll use the image’s web address (URL).
Let’s see how to add an externally hosted image with Markdown syntax:
We make sure to replace the bracketed URL with the actual web address of the image we want to show.
Before including an image, let’s ensure we have permission to use it. Furthermore, we should use reliable URLs that won’t change over time because broken images can make our GitHub project look outdated.
2.4. Adding Images from Google Drive
We can also use cloud storage like Google Drive to host images and include them in our GitHub repository.
To add an image to the Markdown file, we first need to upload the image to Google Drive. Then, we can copy the share link for the file and ensure that the permission type is set to Anyone with the link option.
Let’s look at the Link:
https://drive.google.com/file/d/File_ID/view?usp=sharingNext, we need to paste the link inside any text editor or field and copy the Image ID from it:
We don’t need the complete link to add it to the README.md file. Instead, we just need to paste the File ID inside the markdown code:
Finally, we can Preview or Commit Changes to see the results. Furthermore, we can also use other free image hosting services, like Imgur or Flickr, to do the same task as Google Drive.
3. Conclusion
In this article, we studied how to add images to the GitHub README.md file. First, we learned how to upload images directly to the Markdown file editor using drag-and-drop. Then, we explored other ways of adding images to README.md, like creating a separate repository for images and adding them to Markdown using the relative path.
Lastly, we examined the steps of adding an externally hosted image to the README.md file and covered the steps for using a Google Drive image.