Free README.md template
README template you can copy
A good README.md answers three questions fast: what this project is, how to install it and how to use it.
Copy or download the free template below, fill in its six parts, and check how it looks in the viewer before you push.
The README.md template
Replace the placeholder words, delete any part you don't need, and save it as README.md in the top folder of your project.
# project-name
One line: what it does, and for whom.
## Install
```bash
# the one command people copy
your-install-command
```
## Use it
```bash
# the shortest example that works
your-example-command
```
## Options
| Option | Default | What it does |
|------------|---------|----------------|
| `--option` | `value` | One short line |
## To do
- [x] Something that's done
- [ ] Something that's planned
## License
Name the license here (for example MIT), and add a LICENSE file.The six parts of a good README
Name and one line
The project's name as the only level-1 heading, then one sentence on what it does and who it is for. It's the first thing people read.
Install
The exact command, in a code block so it can be copied in one go. Mention anything people need first, such as a language version.
Use it
The shortest example that really works, again in a code block. One working example beats a page of explanation.
Options
Settings in a table: the name, the default and one short line each. A table is easier to scan than a list of sentences.
To do
A checkbox list of what's done and what's planned, so people can see where the project is going and what help would be welcome.
License
Name the license and add the LICENSE file, so people know how they may use your work.
Keep it short and easy to scan
Use headings so people can jump to the part they need; GitHub and the markdownwise viewer build a contents list from them. Put anything people will copy in a code block. If something doesn't work yet, say so in the To do list rather than leaving people to find out. Every mark used in the template is explained in the Markdown cheat sheet, and the options table follows the Markdown table guide.
Check it before you push, send it as a PDF
Drop your README.md into the free Markdown viewer to see it formatted at once, with a contents list for the headings and nothing uploaded. Need to send it to someone who doesn't use GitHub? Press Make a PDF in the viewer, and the Markdown to PDF converter turns it into a PDF with the tables, code and checkboxes intact.
README questions
What should a README include?
At least what the project is, how to install it and how to use it. A fuller README adds the options, a to-do list and the license, as the template on this page does.
Where does README.md go?
In the top folder of your project. GitHub shows it on the project's front page, under the list of files.
Is README.md written in Markdown?
Yes. The .md ending means Markdown, so headings, code blocks, tables and checkboxes all work; the Markdown cheat sheet lists every mark.
How do I preview a README before I push it?
Drop it into the free Markdown viewer: it shows the file formatted, with a contents list, and nothing is uploaded.
Can I use this README template for free?
Yes. Copy it, download it and change it as you like.