Introduction

GitHub renders README.md files using Markdown, so adding an image is usually just a matter of writing the correct path. The part that trips people up is not the syntax itself, but choosing a path that still works after the repository is cloned, moved, or viewed on another branch.

Use Standard Markdown for Most Cases

The normal Markdown syntax is:

![Architecture diagram](docs/images/architecture.png)

The text inside the square brackets is the alt text. It helps accessibility and also appears if the image cannot be loaded.

The path inside the parentheses can be:

• a relative path to a file in the repository
• an absolute GitHub URL to an externally hosted image
• a raw content URL when you need to reference a specific file directly

For repository documentation, relative paths are usually best because they continue to work across forks and local clones.

Store Images Inside the Repository

A simple project layout might look like this:

1README.md
2docs/
3  images/
4    setup.png

If README.md is at the repository root, reference that image like this:

![Setup screen](docs/images/setup.png)

If the README lives in a subdirectory, the path must be relative to that file instead of the repository root.

This is easy to verify locally. Open the repository tree and ask, "How do I walk from the README file to the image file?" That path is what Markdown should contain.

External Images Also Work

You can link to an external URL:

![Status badge screenshot](https://example.com/assets/status.png)

This is convenient, but it is less reliable for long-term documentation. If the external host changes permissions, rate limits requests, or deletes the file, the README breaks.

For project docs that need to survive over time, storing the image in the repo is usually the better tradeoff.

Resize or Align Images With HTML

Markdown itself does not provide rich image sizing controls. GitHub does allow a limited amount of inline HTML, so when you need a smaller image you can use img markup inside the README.

<p align="center">
  <img src="docs/images/setup.png" alt="Setup screen" width="500">
</p>

This can be useful for wide screenshots or UI walkthroughs. Keep in mind that HTML is a presentation detail; the most portable form is still the plain Markdown version.

Branches and Raw URLs

Sometimes people copy the browser URL of an image file from the GitHub interface. That usually works, but it hard-codes the repository owner, branch, and sometimes a view-specific URL pattern.

A better rule is:

• use relative paths for files that are in the same repository
• use absolute URLs only when the image is intentionally hosted elsewhere

If you need to embed an image from another repository or another branch, use a stable URL and verify it renders in the GitHub preview.

Example README Snippet

Here is a small README section that mixes text and images cleanly:

1## Quick Start
2
3Run the server:
4
5    npm install
6    npm run dev
7
8Open the dashboard shown below.
9
10![Dashboard preview](docs/images/dashboard.png)

That pattern is enough for most repositories. Keep image filenames descriptive and avoid spaces so links stay readable.

Common Pitfalls

The most common mistake is using the wrong relative path. The path is relative to the Markdown file, not to the repository root unless the README happens to be there.

Another problem is hotlinking images from temporary locations such as private tickets, chat uploads, or expiring cloud URLs. Those links often fail later.

A third issue is omitting alt text. The image still renders, but the README becomes less accessible and less clear when the file does not load.

Summary

• Use ![alt text](path) for normal GitHub README images.
• Prefer relative paths for images stored in the repository.
• Keep image files in a predictable folder such as docs/images/.
• Use inline HTML only when you need sizing or alignment.
• Verify the link from the location of the README file, not from the repo root by assumption.