CODEX
Adding Banners and Images to Your Github Repository
Sometimes developer relations projects are about adding marketing appeal to existing content your company offers. Sometimes they’re about clarifying a concept with a diagram. One great way to improve the appeal of your repository is by adding banners to your github repositories. And you can add clarity for difficult concepts with a diagram.
When you add a banner, it makes the repository look more official, and it helps brand active, stable company repositories. You can use banners to show a repository is tended regularly, to draw the reader’s eye so they check out your readme file and project, and even to provide quick details about what the repository contains. For important technical concepts, including diagrams detailing how something works can make your repository more usable.
There’s two places you may want to use a banner or diagram in Github:
- Your readme file
- Your social preview
Your Social Preview
The social preview section on github is available for every repository. This lets you decide what will appear when you share your repository on social media. It provides a template for creating the perfect image, and it’s easy to add your image file. To add an image, take these steps:
- Navigate to a repository you have access to on github.
- From the list of choices across the top of the page, on the far right, click Settings. You’ll see a section labeled Social preview.
- In the Social preview section, click download template and follow the instructions the template provides. If you don’t want to download the template, you can also follow the instructions listed above this link, which indicate that your image should be at least 640x320px, with 1280x640px being best for display.
- When you have your image file ready, click Edit.
- Browse for your image file, and upload it. It will appear immediately in the window under the Social preview section. If it looks good, you can navigate away from this page. Your image is instantly saved after you add it.
Your Readme File
It’s great to include a banner at the top of your repository’s readme file. To do this, all you need to do is:
- Prepare a banner. The banner dimensions are best if they’re 1280x640px.
- At the top of your repository, click Add file. From the choices listed in the drop-down, choose Upload files.
- Upload your image. Save the link that leads to where your image is stored, you’ll need it. For our walkthrough, we’ll pretend the link is https://github.com/user/banner.png
- On your readme, click the pencil icon in the upper right corner. This will make the readme editable.
- At the top of the readme, add the line:
What this does is tell the markdown interpreter that you want to add your banner here, but you don’t want to include alternative text for your banner (because you left it empty between the brackets). - Click Preview. Your beautiful banner will now be visible on your readme file. It looks great! Now commit your change, and voila! a brand new banner.
- You can add the banner to other repositories by uploading the image each time, or if you want to make it easy to update, you can link to the banner you added here across your repositories. That way, if you ever change the banner, it will change it everywhere you added it with that same link. Make sure to keep the same link though!
- You can use this process to add any image to your readme file you like. Make sure you upload the image you want to use to your repository, or have it stored somewhere online where you can access it with a link.
