Web Performance Exploring Video Hosting The Art of Compromise: How Lossy Compression Works Understanding the ‘Image Loading Error’: Comprehensive Guide A Comprehensive Guide to Resizing Images on iOS VBR vs CBR: Understanding Bitrate for Optimal Media Handling Displaying Images with Python’s Top 5 Image Libraries 4 Ways to Add Images to GitHub README + 1 Bonus Method Converting Images with Python JavaScript Image Optimization Techniques Building an Image Picker in React with react-native-image-crop-picker 6 Ways to Save Images in Python 5 Ways to Import Images in React + Bonus Automation Method Extract Text from Images in Python with Pillow and pytesseract Downloading Image from URL in Python: 5 Ways with Code Examples Image.open Python Function: Syntax and Quick Tutorial Complete Guide to Video SEO & Automating It With Cloudinary A Complete Guide To Website Image Optimization Video Encoding: How It Works, Formats & Best Practices The Developer’s Guide to PDFs Integrating Cloudinary With Gatsby For Image Optimization Mastering Image Optimization With Netlify And Cloudinary Seamlessly Integrate Cloudinary With Netlify For Optimised Website Assets Ultimate Guide to Asset Optimization Using Cloudinary and Netlify Adding Video To Magento Understanding Magento Media Adding a Video Widget to Your Website: What You Need to Know SDR vs. HDR: Differences and 5 Considerations for Content Creators Audio Manipulation In PHP Image Management Systems: Key Capabilities and Best Practices Video CDN: Why You Need It and Top 5 Video CDNs Video Optimization: Why You Need It and 5 Critical Best Practices Multi CDN: 8 Amazing Benefits, Methods, and Best Practices What Is an Optimized Website and 6 Ways to Optimize Yours Understanding Image Hosting for Websites Sprite Generation with CSS and 4 Automated Tools 8 Image SEO Optimization Tips to Improve Your Search Rankings Website Speed: 5 Reasons Your Site is Slow and How to Fix It Web Performance: What is it, Trends and Insights for 2024

4 Ways to Add Images to GitHub README + 1 Bonus Method

add image to readme

What is a README.md in GitHub? 

GitHub is a popular platform for storing, managing, and sharing source code. A README.md is your GitHub repository’s welcome mat, showing users what your project can do and even serving as a form of documentation. It’s formatted using Markdown, a lightweight markup language that allows you to style your writing with special characters that can be interpreted and formatted by browsers.

The README.md is usually the first file visitors see when they visit your repository. It should provide an overview of your project, instructions on how to install or use it, and any other essential information. It can also include examples of use cases, highlight specific features, or even provide information on how to contribute to your project if it’s open source.

The README.md is not just a plain text file; it’s a canvas where you can embed images, GIFs, and videos to make your repo easier to understand and use. Adding visual elements provides context to your code and can be the difference between a passerby and a new contributor or user.

This is part of a series of articles about image optimization.

In this article:

    1. Adding Images with Drag and Drop
    2. Adding Images using Relative Paths in Markdown
    3. Adding Images using External URLs in Markdown
    4. Using Base64 Encoding in Markdown
    5. Bonus Method: Use an Image Hosting Service

4 Methods to Add an Image to GitHub README 

Let’s look at four ways to add images to your GitHub repository’s README file. All these methods require editing your README file.

To edit your README file:

  1. Sign into GitHub.
  2. Access your GitHub repository.
  3. Scroll down past the list of folders and file.
  4. Click the pencil icon at the top right of the README frame.

add image to readme

1. Adding Images with Drag and Drop

The easiest way to add images to your README.md is to drag and drop an image file directly into the README editor. 

Open the folder containing the image you want to add. Click the image and drag it into the README.md code in the position you want it to appear.

add image to readme

GitHub will upload the image to your repository and then display Markdown code that displays the image:

add image to readme

Click Preview to see how the image looks, or Commit changes if you want to update the README with the new image.

2. Adding Images using Relative Paths in Markdown

Another option is manually uploading the image file to a folder in your GitHub repository. Then, you can reference it in your README.md using relative links.

For example, if you have an image named example.png and upload it to an images folder, you can add it to your README.md like this:

![Alt text](images/example.png)

The Alt text is the alt attribute for the image, which is useful for accessibility and when the image cannot be displayed. The path inside the parentheses is the relative path to the image in your repository.

3. Adding Images using External URLs in Markdown

Sometimes you might want to reference an image hosted outside your repository. This can be an image from a website, a cloud storage service, or a CDN. The process is similar to adding images with relative paths, but you’ll use the external URL instead of the path.

Here’s how you can do it:

![Alt text](https://example.com/path/to/image.png)

Just replace the URL within the parentheses with the direct link to your image. Be mindful of the rights and permissions associated with the external image you are using. Ensure the URLs are stable and won’t change over time, as broken images in your README can make your project look neglected.

4. Using Base64 Encoding in Markdown

Base64 encoding is another method for adding images to your README.md. This technique involves converting your image into a Base64 string and embedding it directly into your Markdown file. Although this is a fairly uncommon practice, it’s a neat option that may be useful.

Note: While Base64 encoding makes your README.md self-contained, it also makes the file considerably larger and more cumbersome to edit. This method is generally recommended for small images like icons or badges.

You first need to convert the image to a Base64 string, which can be done with a variety of free Base64 encoders. Then, embed the image in your README like this:

![Alt text](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...)

5. Bonus Method: Use an Image Hosting Service

You can use an external image hosting service if you don’t want to include images directly in your repository or embed them with Base64. Services like Cloudinary let you upload images and serve them in any size and format with automated transformations. Get a free Cloudinary account and try it out.

Note: This method is useful if you have large images that would bloat your repository size or want an easy way to manage and transform your images. 

After uploading your image to the hosting service, you’ll be given a direct link that you can use in your README.md file. In Cloudinary, the URL will look like this:

https://res.cloudinary.com/demo/image/upload/sample.jpg

The process is similar to using external URLs:

    ![Alt text](https://res.cloudinary.com/demo/image/upload/sample.jpg)

add image to readme

How to Resize an Image in GitHub README

Once you’ve added an image to your README.md, you might want to resize it to fit properly within the file. Markdown itself doesn’t offer a native way to resize images, but you can leverage HTML tags within your Markdown file to achieve this.

Here’s how to resize an image using HTML:

<img src="images/example.png" width="300" />

In this example, the width attribute is set to 200 pixels. You can adjust the width to suit your needs, and the height will scale accordingly to maintain the aspect ratio.

Note: Including HTML tags can make your README file difficult to read. Also, it resizes the images on the client side, which is wasteful because users need to download the full size of the original image.

If you use Cloudinary to host your images, resizing them on the server side is easy, just by changing the URL. Here is how to resize the image above to 200 pixels wide directly in markdown:

    ![Alt text](https://res.cloudinary.com/demo/image/upload/w_300/sample.jpg)

Cloudinary can do much more than resize your images. For example, you can automatically crop your image with content-aware, AI-based features. For example, this code crops the image to the most interesting area, as determined by AI:

add image to readme

https://res.cloudinary.com/demo/image/upload/c_crop,g_auto,h_250,w_200/docs/hot-air-balloons.jpg

Cloudinary offers a generous free plan—get a free account and host, deliver, and transform images for your software and web projects.

QUICK TIPS
Tamas Piros
Cloudinary Logo Tamas Piros

In my experience, here are tips that can help you better manage and optimize adding images to your GitHub README files:

  1. Use descriptive alt text for accessibility and SEO
    Always include descriptive alt text when adding images to your README. This not only improves accessibility for visually impaired users but also boosts your project’s visibility in search engines. Use clear, concise descriptions that accurately represent the content of the image.
  2. Leverage version control with relative paths
    When using relative paths to include images from your repository, ensure the images are under version control. This way, changes to the images or their locations are tracked, and you can revert to previous versions if needed. This also ensures consistency when working in teams.
  3. Optimize images before uploading
    Compress and resize images before adding them to your repository to reduce loading times and repository size. Use tools like ImageOptim or online compressors to minimize file sizes without sacrificing quality. This is especially important for large images or repositories with multiple images.
  4. Organize images in a dedicated folder
    Create a dedicated folder (e.g., /images or /assets) within your repository to store all images. This keeps your project organized and makes it easier to reference images in your README. It also helps prevent clutter in the root directory, maintaining a clean project structure.
  5. Check external URLs for reliability
    When linking to images hosted externally, ensure the URLs are stable and reliable. Use trusted hosting services or your own server to avoid broken links. Periodically check the external links in your README to ensure they remain functional.
  6. Consider repository size implications with Base64
    Be cautious when using Base64 encoding for images, as it significantly increases the size of your README file. This can make the file slower to load and harder to edit, especially in large repositories. Reserve this method for small, essential images like icons or badges.
  7. Use Cloudinary for dynamic image handling
    Cloudinary’s URL-based transformations allow you to dynamically resize, crop, and optimize images directly from the link used in your README. This reduces the need to manually edit and re-upload images, streamlining your workflow and improving load times.
  8. Maintain consistent image styles
    Keep a consistent style for all images in your README to create a cohesive and professional appearance. This includes maintaining uniform sizes, borders, and alignments. Consistency helps in maintaining visual harmony and improving the readability of your documentation.
  9. Test README display across different platforms
    After adding images, test your README display across different devices and platforms (e.g., GitHub Desktop, mobile browsers) to ensure the images render correctly and the layout is preserved. This ensures that all users, regardless of their device, have a consistent experience.
  10. Document image sources and credits
    If you use images from external sources, provide proper credits and documentation within your README or a dedicated section in your repository. This is particularly important for open-source projects to respect copyright and licensing agreements.

These tips will help you effectively manage images in your GitHub README, ensuring they enhance your documentation and provide a better user experience

Last updated: Aug 23, 2024