How to add images to README.md on GitHub?
Recently I joined GitHub. I hosted some projects there.
I need to include some images in my README File. I don’t know how to do that.
I searched about this, but all I got was some links which tell me to "host images on web and specify the image path in README.md file".
Is there any way to do this without hosting the images on any third-party web hosting services?
41 Answers 41
Try this markdown:
I think you can link directly to the raw version of an image if it’s stored in your repository. i.e.
You can also use relative paths like
Also try the following with the desired .fileExtention :
- You can create a New Issue
- upload(drag & drop) images to it
- Copy the images URL and paste it into your README.md file.
here is a detailed youTube video explained this in detail:
It’s much simpler than that.
Just upload your image to the repository root, and link to the filename without any path, like so:
You can also add images with simple HTML tags:
Many of the posted solutions are incomplete or not to my taste.
- An external CDN like imgur adds another tool to the chain. Meh.
- Creating a dummy issue in the issue tracker is a hack. It creates clutter and confuses users. It’s a pain to migrate this solution to a fork, or off GitHub.
- Using the gh-pages branch makes the URLs brittle. Another person working on the project maintaining the gh-page may not know something external depends on the path to these images. The gh-pages branch has a particular behavior on GitHub which is not necessary for hosting CDN images.
- Tracking assets in version control is a good thing. As a project grows and changes it’s a more sustainable way to manage and track changes by multiple users.
- If an image applies to a specific revision of the software, it may be preferable to link an immutable image. That way, if the image is later updated to reflect changes to the software, anyone reading that revision’s readme will find the correct image.
My preferred solution, inspired by this gist, is to use an assets branch with permalinks to specific revisions.
Construct a «permalink» to this revision of the image, and wrap it in Markdown.
Looking up the commit SHA by hand is inconvenient, however, so as a shortcut press Y to a permalink to a file in a specific commit as this help.github page says.
To always show the latest image on the assets branch, use the blob URL:
/Downloads , /tmp , etc.).
You can also insert animated SVG images in the markdown file like any other format.
It can be a good alternative to GIF images.
Example (assuming the image is in assets directory in the repository):
To use different images based on GitHub dark/light theme see this post.
Very Simple : Can be done using Ctrl + C/V
Most of the answers here directly or indirectly involve uploading the image somewhere else & then providing a link to it.
It can be done very simply by just copying any image and pasting it while editing Readme.md
- Copying the image — You can just click on the image file and use Ctrl + C or may copy the screenshot image to your clipboard using the snipping tool
- You can then simply do Ctrl + V while editing Readme.md
Guithub will automatically upload it to user-images.githubusercontent.com and a link to it will be inserted there
Commit your image (image.png) in a folder (myFolder) and add the following line in your README.md:
I need to include some images in my README File. I don’t know how to do that.
I created a small wizard that allows you to create and customize simple image galleries for your GitHub repository’s readme: See ReadmeGalleryCreatorForGitHub.
The wizard takes advantage of the fact that GitHub allows img tags to occur in the README.md . Also, the wizard makes use of the popular trick of uploading images to GitHub by drag’n’dropping them in the issue area (as already mentioned in one of the answers in this thread).
- Create an issue regarding adding images
- Add the image by drag and drop or by file chooser
Then copy image source
Now add  to your README.md file
Alternatively you can use some image hosting site like imgur and get it’s url and add it in your README.md file or you can use some static file hosting too.
Basic Syntax
- my-image-alt-tag : text that will be displayed if image is not shown.
- url-to-image : whatever your image resource is. URI of the image
Example:
This will look like the following:
You can now drag and drop the images while editing the readme file.
Github will create a link for you which will be in the format of:
Alternatively, at the bottom of the file, it says "Attach files by dragging & dropping, selecting or pasting them". If you click on that one, it will give you an option to upload a file directly or you can just paste it!
Where ![A test image] is your alt text and (image.png) is the link to your image.
You can have the image on a cloud service or other online image hosting platforms Or you can provide the image link from the repository if it is in the repo
You can also make a specific folder inside your repository dedicated to your readme images
Just add an <img> tag to your README.md with relative src to your repository. If you’re not using relative src, make sure the server supports CORS.
It works because GitHub support inline-html
Step by step process, First create a folder ( name your folder ) and add the image/images that you want to upload in Readme.md file. ( you can also add the image/images in any existing folder of your project. ) Now,Click on edit icon of Readme.md file,then
After adding image, you can see preview of changes in the, «Preview Changes» tab.you will find your image here. for example like this, In my case,
app folder -> src folder -> main folder -> res folder -> drawable folder -> and inside drawable folder refrence_image.png file is located. For adding multiple images, you can do it like this,
Note 1 — Make sure your image file name does not contain any spaces. If it contain spaces then you need to add %20 for each space between the file name. It’s better to remove the spaces.
Note 2 — you can even resize the image using HTML tags, or there are other ways. you can google it for more. if you need it.
After this, write your commit changes message, and then commit your Changes.
There are many other hacks of doing it like, create a issue and etc and etc. By far this is the best method that I have came across.
3 Ways to Add an Image to GitHub README
Images often come in handy alongside documentation. Here are a few methods for adding them to your README and other markdown files.
Images can be a great way to enhance your documentation in README files or other markdown documentation. While there is a standard way to add an image in markdown, the nuance is in the image's source. Here are three methods for adding images to markdown files in a GitHub repository.
Markdown Syntax
The original documentation specifies that images should be written like so:
HTML code is also valid within most markdown renderers, including GitHub's flavor. That means you could also render an the image above like this:
This is a great option if you want to add a little custom styling to your image. For example, if you want to control the size or alignment of the image, you might do something like this:
Method #1: Local File
The first method is to commit the image directly to your GitHub repository. When you do that, you can use a path to that file for the src , which should be relative from the markdown file.
In other words, if you place an image file in the root your project as my-image.jpg , you could then render the image in your projects main README.md file like this ( title omitted for simplicity):
Let's say the image file was instead in an images directory. Then your code in the project's main README file would look like this:
Now, let's say that you have another README file in your src directory, but your image is still in the images directory. Then your relative path looks like this:
This approach is a quick and easy option, as long as you don't have too many images to manage. If you end up using a lot of images, I'd consider another route .
Method #2: Remote File
Another option is to use some external file hosting service to provide your image, such as S3 or Dropbox. In this case, you could get the direct and full URL to the image and then use that.
Method #3: Uploaded File
Lastly, you could use GitHub to host the image for you. This one is a little goofy, but it totally works!
The trick is to add them to some comment — an issue, pull request or discussion — and then grab the resulting URL.
You can drag and drop the image from your computer to a comment field in GitHub. Wait for the file to upload and then the URL to the image is right there! You don't even have to submit the issue if you don't want to (although that may limit the image's lifespan).
Unlike the other two options, I see two issues with this approach:
- On its own, it becomes difficult to know the source of the image. Maybe that's not a big deal, or maybe you have a way to streamline it — e.g. all your images go into a single "Images" issue that stays open.
- The purpose of images in comments is technically to serve the comment. It's possible GitHub changes these URLs without notifying you.
Inspiration & Resources
This post was originally inspired by this tweet from @DavidDarnes:
Haha nice! FYI if you upload those readme images in a new GitHub comment and it'll give you the image paths back to put them in your readme, then you won't have them cluttering the repo 😶
— Dave 🧱 (@DavidDarnes) January 18, 2021
I ended up being more comprehensive than just this singular suggestion, which came to be more in-line with this StackOverflow question.
Как написать красивый и информативный README.md
Многие программисты лихо управляются с кодом и знают мельчайшие подробности своих проектов. Но некоторым из них (в том числе и мне) недостаёт коммуникативных навыков.
Удивительное дело: программист может потратить час на подгонку внутренних и внешних отступов для одной-единственной кнопки и не найти каких-то 15 минут на файл Readme описания проекта.
Надеюсь, вы уже знаете, что такое файл readme.md и для чего он нужен. На всякий случай попробую объяснить.
Что такое Readme.md?
README (буквально означает «прочти меня») — это первый файл, который нужно читать, получив доступ к проекту на Github или любой Git-хостинговой площадке. Этот файл в первую очередь и предлагается вниманию пользователя, когда он открывает здесь репозиторий того или иного проекта. Такой файл содержит кучу полезной информации, так что его вполне можно рассматривать как справочное руководство по проекту.
Посмотрите, где у нас здесь файл Readme:
Файл Readme.md находится в корневой папке репозитория и автоматически отображается в каталоге проекта на github.
Расширение .md — это сокращение от слова markdown. Это язык разметки для форматирования текста. Его используют (как и язык разметки HTML) для нормального отображения документов.
Вот как выглядит файл разметки на github (здесь использован VSCode, который одновременно показывает нам файлы разметки и в режиме предварительного просмотра):
Здесь можно найти официальный гайд Github для формата разметки на тот случай, если вам захочется основательно разобраться в языке разметки.
Русские Блоги
1. Сначала поставьте картинку в локальную папку. Нажмите на удаленный склад GitHub.
2, введите склад удаленного GitHub в браузере, чтобы найти изображение, чтобы открыть изображение. Затем текущая ссылка браузера — это адрес изображения. Скопируйте URL картинки.