Clique aqui para ler em português
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
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
[](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
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:
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! 😊😊
Top comments (0)