DEV Community

Lee Twito
Lee Twito

Posted on

10 must-know tips for crafting the perfect looking README.md for your GitHub repo (with examples)

#webdev #opensource #github

1. Center Your Elements

Bring elements like your logo or headings to the center to make them pop.

Example:

<div align="center">
  <img src="your-logo-url" alt="Logo" width="320" />
</div>
Enter fullscreen mode Exit fullscreen mode

2. Responsive Logo

Use <picture> and <source> to make your logo responsive and cater to different color schemes.

Example:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="dark-image-url">
  <img src="light-image-url" alt="Logo" />
</picture>
Enter fullscreen mode Exit fullscreen mode

3. Add Badges

Use badges to highlight important info like license, stars, docs, and more.
Visit shields.io and choose from their collection.

Examples:

[![MIT License](https://img.shields.io/github/license/tutim-io/tutim)](https://github.com/tutim-io/tutim/blob/main/LICENSE) 
[![Number of GitHub stars](https://img.shields.io/github/stars/tutim-io/tutim?logo=github)](https://github.com/tutim-io/tutim/stargazers) 
[![Discord is Live](https://img.shields.io/badge/Discord-Live-green?logo=discord&logoColor=%23fff)](https://discord.tutim.io) 
[![Docs are updated](https://img.shields.io/badge/docs-updated-green?color=blue)](https://docs.tutim.io) 
[![Product Hunt](https://img.shields.io/badge/Product%20Hunt-Launch%20soon-orange?logo=producthunt&logoColor=%23fff)](https://www.producthunt.com/@leetwito)
Enter fullscreen mode Exit fullscreen mode

4. Demo GIF

Include a demo GIF to give users a quick preview of your project.
Extra: You can just drag-and-drop your GIF file into GitHub's editor.

5. Feature List

List your project's features in bullet points to make it easy for users to skim through.

Example:

### ✨ Features

- 🌈 Headless
- 💅 Rich form
- 🚀 Performant
Enter fullscreen mode Exit fullscreen mode

6. Getting Started

Provide a quick start guide with clear instructions and code snippets.
Make sure to visualize the output, outline requirements, and keep it simple.

7. Code Examples

Give clear examples of how to use your project, with detailed code snippets.

8. Community and Support

Include links to your community, like Discord, Twitter, and contribution guidelines.

Example:

### 🤵 Need Help?

Join our [Discord server](https://discord.tutim.io) or [Open an issue](https://github.com/tutim-io/tutim/issues/new/choose)

### 🔗 Links

- [Home page](https://tutim.io)
- [Twitter](https://twitter.com/Tutim_io)
Enter fullscreen mode Exit fullscreen mode

9. Star History

Display your repo's growth with a Star History chart.

Example:

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=tutim-io/tutim&type=Date)](https://tutim.io/developers)
Enter fullscreen mode Exit fullscreen mode

10. Showcase Contributors

Acknowledge and celebrate the people who've contributed to your project by displaying their avatars.

Example:

### 💪 By the community, for the community

![](https://contrib.rocks/image?repo=your-username/your-repo)

Powered by [your-project-name](https://your-project-url)
Enter fullscreen mode Exit fullscreen mode

11. Share your tip! Or let me know if this was insightful for you

Top comments (0)

Read next

maieonbrixx profile image

Structuring Your React Applications with "Layout Primitives": Today, let's focus on the unbeatable <Stack /> 🚀

Mahdy -

lovestaco profile image

From Lama2 to LiveAPI: Building Super-Convenient API Documentation (Part II)

Athreya aka Maneshwar -

aadenboy profile image

Turning VSCode Into an Art Program (sorta)

aadenboy -

endeo profile image

Beyond the Hype: Four GameFi Trends Set to Redefine Gaming

Paul Osadchuk -