How to use the readme generator
- Enter the project name, an optional one line summary and a description.
- List features, one per line, and add the install commands and a usage example with the code language for each.
- Choose a license name, add a contact line if you want one, and decide whether to include a Contributing section.
- Copy the Markdown or download README.md. Empty fields are left out.
A small command line project
A name, a description and an install command produce a README that starts with a level one heading for the name, then the description, then an Installation heading above a fenced code block that holds the command.
Adding two features gives a Features list, a usage example gives a Usage section, and choosing MIT adds a License section that names the license and points to the LICENSE file.
What each section is for
The title and description say what the project does. Features give a quick scan of what it can do. Installation and Usage show the shortest path from nothing to a working result, which is the part readers look for first. Contributing tells people how to help, and License tells them what they may do with the code.
The text for Contributing and License is short and general. A License section here only names a license and points to a file. You still need to add a real LICENSE file, and you should pick a license that suits your project, possibly with legal advice.
Code blocks and safety of the output
Commands and examples are wrapped in fenced code blocks. If your code itself contains three backticks, the fence is made longer so the block does not end early. The language name you enter is cleaned to letters, digits and a few symbols so it cannot break the fence.
Names and one line fields have line breaks collapsed into spaces. The output is plain Markdown text for you to read before publishing, and nothing is uploaded. For setup files see the gitignore generator, and for tables inside a README use the Markdown table generator. The JSON formatter and validator helps with any config examples.
Assumptions and limits
- Only sections you fill in are written, except Contributing and License, which you switch on or off.
- The Contributing and License wording is generic and should be reviewed.
- Commands and claims are yours. The tool does not run or test anything.
- Output is standard Markdown with fenced code blocks.
Frequently asked questions
What should a good README include?
A clear name, what the project does, how to install it, a short usage example and the license. Add screenshots, requirements and links as your project grows.
Does choosing a license add the license text?
No. It only names the license in the README. You must add a LICENSE file with the full text yourself.
What file name should I use?
Use README.md at the top of the repository. Hosting sites show it automatically on the project page.
Why are some of my sections missing?
A section is written only when its field has text. Fill in the field, such as usage, and the section appears.