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

farouk_ profile image

Task manger app

Farouk -

iamdevmarcos profile image

React Hydration Explained 🔥

Marcos Mendes -

ronieremarques profile image

Roniere Marques: Um Desenvolvedor em Destaque

Roniere da silva marques -

adeleyeayodeji profile image

How to Stop Spam Comments on WordPress WITHOUT Any Plugin

Adeleye Ayodeji -