GitHub is a popular platform for hosting and managing your code repositories. One of the essential aspects of a well-documented project on GitHub is a clear and informative README file. Often, you’ll want to include images in your README to illustrate your project, show screenshots, or add diagrams. In this article, we’ll show you how to add images to your README.md file on GitHub, both using third-party hosting services and without hosting images externally.

The Problem: Need to Add Images to README.md

When you want to add images to your GitHub README file, the most common advice you’ll come across is to host your images on a third-party web hosting service (like Imgur, Dropbox, or a personal website) and then specify the image path in your README.md file. While this method works well, it may not be suitable for all users, especially those who prefer not to rely on external hosting services.

The Solution: GitHub’s Repository Upload

GitHub itself provides a solution to this problem by allowing you to upload images directly to your repository. This method ensures that your images are hosted within your GitHub repository, making it more self-contained and avoiding any reliance on third-party services.

Here’s how you can use GitHub’s repository upload feature to add images to your README.md file:

Step 1: Upload Images

1. In your GitHub repository, navigate to the location where you want to upload your images. You can create a new folder for these images or use an existing one.
2. Click on the “Add file” button and select “Upload files.”
3. Now, you can either drag and drop your image files or use the file picker to select them from your computer.
4. After uploading your images, you will see them listed in the repository. Make sure to provide meaningful file names to keep things organized.

Step 2: Reference Images in README.md

In your README.md file, you can reference the uploaded images using relative paths. For example, if you uploaded an image to a folder named images, you can use the following Markdown code to display the image:

![GitHub Image](/images/your-image.png)

Replace your-image.png with the actual file name of your image.

Step 3: Commit and Push

Once you’ve added the image references to your README.md file, make sure to commit your changes and push them to your GitHub repository. This will make the changes and images available for others to see.

Using External Hosting Services

While GitHub’s repository upload is a convenient way to include images in your README.md file, it might not be the best solution for very large or numerous images. In such cases, external hosting services can still be useful.

You can follow the traditional method of hosting images on third-party websites and specifying their URLs in your README.md file. This is a viable option when you don’t want to increase the size of your repository with numerous images.

Here’s an example of how you can reference an image hosted externally:

![External Image](https://example.com/path-to-your-image.png)

Raw GitHub URL for Image within Repository / Branch

If you need to reference an image that’s located within a separate repository, GitHub does have a “raw” URL that can be used to reference the image file directly within public repositories.

The following is an example of a “raw” URL for an image in a public GitHub repository:

https://raw.githubusercontent.com/crpietschmann/jHtmlArea/master/img/nuget-package-install.png

You can see the “raw” URL has the following format:

https://raw.githubusercontent.com/{username}/{project}/{branch}/{file-path-in-repo}

The placeholders in the “raw” URL format are as follows:

• {username} – The GitHub username that hosts the repository.
• {project} – The name of the GitHub project / repository.
• {branch} – The Git branch within the GitHub project / repository where the file resides.
• {file-path-in-repo} – The full file path within the repository branch to the image file you want to reference. In the above example this is img/nuget-package-install.png.

The “raw” GitHub URL for an image within a repository can then be used within the markdown of the README.md file the same as any other externally hosted image:

![Raw GitHub Image](https://raw.githubusercontent.com/crpietschmann/jHtmlArea/master/img/nuget-package-install.png)

Conclusion

In this article, we’ve shown you how to add images to your README.md file on GitHub. GitHub’s repository upload feature offers a convenient way to include images directly within your repository, making it self-contained and eliminating the need for external hosting services. However, for very large or numerous images, using external hosting services is a practical alternative.

By following these steps, you can make your GitHub projects more visually appealing and informative, enhancing the overall user experience. Whether you choose to upload images to your repository or use external hosting, you’ll be well-equipped to create well-documented and visually engaging projects on GitHub.