DEV Community

Cover image for Awesome Readme Examples for Writing better Readmes
Suraj Vishwakarma for Documatic

Posted on • Updated on


Awesome Readme Examples for Writing better Readmes


Writing the readme should be your priority after completing the code. But writing a good readme requires some points to cover while writing a Readme. I have written a piece about How to Write an Awesome Readme discussing readme, how to write it, and tools that can assist in this. You can check the discussion section for more insightful stuff.

The only thing that I missed in the article was to mention some good readme examples. So, in this article, I am going to list down some awesome remade that will help you in taking inspiration for writing your reamde.

So, let’s get started.


github repo - athityakumar/colorls

It is a Ruby script to colorize the ls output with color and icons. The readme looks amazing. It starts with the name of the project and then the badges. At the top, we can see a short description of the project with an image to illustrate the idea better.

It covers most of the relevant topics that can be included in the readme. It covers a Table of Content, Installation guide, Contributing, License, and other important stuff. The usage of images is very well illustrated in the readme as I show images of their every feature.

This can easily be used as a template for small projects.


github repo - surajondev/medusa-discord-integration

It is one of the repositories that I created for submitting a project for a hackathon. It can easily be used as a template for submitting projects for a hackathon. I have covered topics such as description, preview, participation details, installation guide, reference resources, and others.

It starts with the name of the project and then a beautiful cover image. I have shown the output of the project by displaying images. You can also use gifs for output.


github repo - public-apis/public-apis

This is a repository that contains numerous APIs that can be used to build an application. The feature of tables in markdown is well-used by such repositories. At the top, we have the link name and sub-title explaining the repository. You can also find all the useful links such as contributing guides, Issues, and licenses at the top of the project.

This kind of list is very huge. That’s having a good structure and a table of content becomes important. This repository has both of them. After every category of API, we have Back to Index link to get back to the table of content.


GitHub repo - forem/forem

A repository containing awesome resources for React ecosystem. The contains most of the required things that you want to see in a readme. It has links to other files too for further explanation on the topic.

The readme is not long but still, they have a table of content. That show, their efforts for making it even better. They have covered the topics such as Contributing, Getting started, developer documentation, license, and others.

I contributed to their repository and the guide helped me a lot in setting up the project.


github repo - refinedev/refine

Refine is an open-source, headless web application framework. The readme file looks beautiful with images, badges, and emojis that they have included in it.

At the top, the name of the project with a short description. They have added all the useful links at the top for convenience. It addresses all the information that is related to the project. They have covered all the important topics such as setting up projects, contributions, licenses, and others.


This repository is an example of a great reamde structure. You can use them as a template to write your own reamde according to your requirement. I hope that the article has helped you in providing some awesome readme to inspire your next project’s readme.

Thanks for reading the article.

Top comments (2)

surajondev profile image
Suraj Vishwakarma

Mention some of your favorite readme here👇

lexlohr profile image
Alex Lohr

Super Useful CSS Resources

A collection of 70 hand-picked, web-based tools which are actually useful.
Each will generate pure CSS without the need for JS or any external libraries.