Markdown makes it simple to embed images in your GitHub profile. First, however, you will need to upload the image to your GitHub profile repository so you can link to it from there. This page will walk through the steps to create a new directory in your repo, and upload your image to the new directory. Pick an image you'd like to include in your profile. If you simply wish to follow along, any image will do!

Create a New Directory with a README

It's simple to create a new directory in a repository on GitHub. However, to do so, you must add a file to it. This is not an issue as it is always a good idea to put a simple README in a GitHub directory to explain what the directory is for. It can obviously be more detailed than that, but for our purposes, simple is perfect.

On GitHub, go to the main page for your special repository. You'll see an Add file dropdown. Click Add File, and then click Create new file.

In the empty box at the top, preceded by your repo name followed by /, you'll want to type the following:


As soon as you type /, it will turn it into a directory under the repo name, leaving you with a newly empty box to enter a file name. Enter the following:

Now, click in the file editor, and add a Markdown level two heading with a quick description of what will be in this directory.

The edited sections should now look something like this:

Now, commit your changes. Once committed, you should see something similar to the following.

You'll find an Add file dropdown towards the top-right. Click Add file, and then click Upload files.

Once in the file upload dialogue, you'll see clear instructions as to what to do next.

You have two choices: you can drag a file to that section of the window, or you can click choose your files and upload through a file explorer dialogue.

Choose your method, and upload your image file. You'll see the following while it uploads.

Once uploaded, it will show up below the instruction box, appearing something like the following.

Commit the uploaded image exactly as you would changes to your README files. Once committed, it should return you to the main page of your repository. Here you'll find your new assets directory. Click it.

Within it, you'll find the image you uploaded. You can click it to view it, if you like.

Now you have an image you can link to. This means you're ready to include an image in your GitHub profile using Markdown!

This guide was first published on Jul 06, 2022. It was last updated on Jun 07, 2022.

This page (Add an Image) was last updated on Jun 23, 2022.

Text editor powered by tinymce.