GitHub README Generator

What is GitHub README Generator?

A README is the first file people read in a repository. It says what the project does, how to install it, how to use it and under which license it can be used. A project without one is hard to try and easy to skip. Fill in the boxes above and the README.md is written for you as you type. Sections you leave empty are left out, so you only get what you filled in. Switch to Preview to see roughly how it will look on GitHub, then copy the Markdown or download the file. Everything runs in your browser, so your project details are never uploaded.

How to Write a README

1. 1

   Name and describe the project: Give the project name and a one-line description. This is what people see first, so say what it does in plain words.

2. 2

   Add features, stack and steps: List features one per line, name the tools it is built with, and paste the install and usage commands. They are shown as code blocks.

3. 3

   Choose a license: Pick the license that fits and add your name. A license badge and a license section are added for you.

4. 4

   Check the preview: Switch to Preview to read it the way a visitor will, then go back and change anything that reads badly.

5. 5

   Copy or download: Copy the Markdown, or download README.md and commit it to the root of your repository.

What a Good README Includes

• A clear first line: One sentence on what the project is and who it is for.

• How to install it: Commands that work if copied exactly. Test them on a clean machine if you can.

• How to use it: One or two real examples beat a long description.

• How to help: A short note on how people can report a bug or send a change.

• The license: Without one, other people have no permission to use or change your code.

Choosing a License

This tool adds the license name and a badge to your README. It does not add a LICENSE file, so also add the full license text to your repository. GitHub can add it for you when you create a repository or from the Add file menu. This is not legal advice.

• MIT: Short and permissive. People can use the code freely if they keep your notice.

• Apache 2.0: Permissive, with an explicit patent grant.

• GPL 3.0: Copyleft. Changes shared with others must stay under the same license.

• BSD 3-Clause and ISC: Permissive licenses similar to MIT.

• Unlicense: Gives the code to the public domain.

Markdown Tips for README Files

• Headings: # is the title and ## starts a section. GitHub builds a table of contents from them.

• Code blocks: Three backticks start and end a block. Add a language name after the first three for colour.

• Images and badges: Add them once the README is on GitHub. The preview here does not load images, so nothing is fetched from outside your browser.

• Keep it scannable: Short sections and short lines. Most visitors skim.