Awesome README
Tags: readme, githunt, project, awesome
Published: 2021-07-01 02:49:23

[Clique aqui para ler em português](https://medium.com/walternascimentobarroso-pt/awesome-readme-3e5529a90a7c)

When entering a project, before looking at code the first information we see is what’s in the README, so nothing more fair than making a spectacular README.

## Logo

If the system already has a defined logo, we start with it
```
![Logo](https://via.placeholder.com/150x150)
```

## Title

Leave a title for your project, if you don’t have a good name, you can put the project name.
```
# title
```

## Badge

The badges, besides making it more elegant, help us with quick information so if possible add it to your project, an example would be the travis badge that informs you if you passed the test or not
```
[![Build Status](https://travis-ci.org/walternascimentobarroso/walternascimentobarroso.github.io.svg?branch=master)](https://travis-ci.org/walternascimentobarroso/walternascimentobarroso.github.io)
```
Note: if you want to create your own, https://shields.io/ is a great tool

## Menu

By leaving it very descriptive, the README ends up getting too extensive, so as not to generate a tiring reading, it is interesting to have a small menu.
```
[Overview](#overview)
•
[Doc](#doc)
•
[Demo](#demo)
```
if the menu is too big change from horizontal to vertical.
```
## :bookmark_tabs: Menu

* [Overview](#overview)
* [Doc](#doc)
```
Note: Insert README topics in links to facilitate reader navigation

## Overview

Here you should give a quick description of what the system does.
```
## :scroll: Overview
Brief description of the project.
```

## Screenshot

Not everyone has time to check and run the project, the ideal is to have some screenshots of the project right at the start
```
## :rice_scene: Screenshot

![Logo](https://via.placeholder.com/750x500)
```
Note: A gif showing the project is very useful.

## Demo

Now comes one of the most important parts, the demo, if your project is already published and you have a way to test it without having to download the project, leave the link for quick access here, and if you need to login, leave the data here too.
```
## :dvd: Demo

Lorem ipsum dolor sit amet consectetur, adipisicing elit.

| url                      | login          | password |
| ------------------------ | -------------- | -------- |
| http://exemplo.com/admin | admin@mail.com | 123      |
```

## Documentation

If your system has documentation, leave a link to it here.
```
## :blue_book: Documentation

Documentation lives at readthedocs.org
```

## Requirements

If you want them to use your system, leave the necessary prerequisites described here, this way you avoid after downloading having to go through all the files and check which items are needed.
```
## :heavy_exclamation_mark: Requirements

* [Node](https://nodejs.org/en/download/)
* [PHP](https://php.net/)
```

## Installation and usage

Here you describe how your system should run for it to work properly
```
## Installation and usage


git clone https://github.com/<user>/<project>
```

Note: Put a step by step to run your application.

### Tests

Put a step by step to run the tests
```
### Tests

$ npm run test
```

### Dependencies and libs

Some like to list each lib used, if you want here is a good place

```
### Dependencies and libs

- [React](https://pt-br.reactjs.org/docs/create-a-new-react-app.html)
- [React PDF](https://react-pdf.org/)
```

### Folder Structure

If the project has a unique folder organization it is useful to make this information explicit.
```
### Folder Structure

.
├── src # Project source code
├── doc # Doc for the project
├── .gitignore
├── LICENSE
└── README.md
```

Note: If you use linux and want to display something like this the tree program is very good `sudo apt install tree -y`

## Release History

If it’s a big project with a lot of improvements already made, it’s nice to have a changelog
```
- 0.2.0
  - CHANGE: Remove function
  - ADD: Add init()
- 0.1.1
  - FIX: Crash when calling baz()
- 0.1.0
  - CHANGE: Rename foo() to bar()
- 0.0.1
  - Init the project
```

## Contributing

Leave a simple way how to contribute to your project
```
1. Fork it (https://github.com/yourname/yourproject/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am ‘Add some fooBar’)
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request
```

### Tasks

If so, list tasks/features that still need to be implemented in your application
```
## :bell: Tasks

- [ ] Task 1
- [x] Task 2
- [x] Task 3
- [ ] Task 4
```

## Authors

If you want to identify the project’s authors, this is the place
```
## :smiley_cat: Authors

- [@walternascimentobarroso](https://walternascimentobarroso.github.io/)
```

## License

Finally add the type of license your project has.
```
## :memo: License

The [MIT License]() (MIT)
```

## Template

To use the full template see the link:

{% gist https://gist.github.com/walternascimentobarroso/dc4bb89ec7951adfa8cc20bedbb53c32 %} 

***

Notes:

* All information is optional, it is not mandatory to use everything, but the more information the better ;)
* As markdown does not have native css adjustment, it is necessary to use some old tags and attributes to simulate a more elegant layout

Extras

Some tools to create your readme

https://readme.so/
https://github.com/kefranabg/readme-md-generator#readme

For other examples see the link below:

https://github.com/matiassingers/awesome-readme

***

## Thanks for reading!

If you have any questions, complaints or tips, you can leave them here in the comments. I will be happy to answer!

😊😊See you! 😊😊