A README generator helps you write a clear README.md for your project in minutes. Fill in the project name, what it does, its features, how to install and use it, how to get help, how to contribute and its license, and this README generator writes a well-structured README in Markdown with a live preview. Copy it or download README.md and add it to your repository.
Why a README matters
GitHub describes the README as the file that tells other people why your project is useful, what they can do with it, and how they can use it. It's often the first thing a visitor sees in a repository. Together with a license, contribution guidelines and a code of conduct, a README sets expectations for your project and helps you manage contributions.
What a good README covers
According to GitHub, README files typically include:
- What the project does
- Why the project is useful
- How users can get started with it
- Where users can get help
- Who maintains and contributes to the project
The generator follows that structure: an about section, features, installation, usage, getting help, contributing, license and author.
How to use the README generator
- Enter the project name and an optional one-line summary.
- Describe what it does and why someone would want it.
- List the features and what it's built with, one per line.
- Add install and usage commands. They're placed in code blocks so they're easy to copy.
- Add help, contributing and author details, and choose a license.
- Switch to Preview to see how it will look, then copy or download README.md.
Where to put the README
Save the file as README.md. GitHub recognizes a README in the repository's hidden .github folder, the root folder or the docs folder and shows it to visitors automatically. If there's more than one, it uses the .github folder first, then the root, then docs. If you add a README to a public repository named after your username, it appears on your GitHub profile page. Content beyond 500 KiB is truncated when the README is viewed on GitHub, so keep it focused.
Headings become a table of contents
GitHub automatically builds a table of contents from the section headings of any Markdown file, including READMEs, available from the Outline menu on the rendered page. Each heading also gets a link anchor, so you can link straight to a section such as Installation. That's another reason the generator uses a clear heading for every section.
Choosing a license
The generator adds a short License section naming the license you pick and pointing to a LICENSE file. It doesn't create the license text itself: add a LICENSE file with the full wording to your repository too. Read each license's full terms before you choose, because they set what others may do with your code. Choose No license section if you'll write it yourself.
Tips for a better README
- Lead with the purpose. One sentence on what it does and who it's for.
- Show, don't tell. A short usage example beats a long description.
- Keep install steps copyable, one command per line.
- Add a screenshot after downloading, if your project has a user interface.
- Keep it current as the project changes.
Is it private?
Yes. Your README is built in your browser and saved only in this browser, so you can come back to it later. Nothing is uploaded.
Writing each section
- Summary: one sentence a visitor can read in a few seconds, such as Check the forecast from your terminal.
- About: a short paragraph on what the project does, who it's for and what problem it solves.
- Features: the main things it can do, one per line, starting with a verb or a noun.
- Built with: the main languages, frameworks and services, so contributors know what to expect.
- Installation: the exact commands to install it, in the order to run them.
- Usage: a real example someone can copy and run, with its typical options.
- Getting help: where to ask questions or report bugs, such as the issue tracker or a discussion forum.
- Contributing: how others can help, and whether they should open an issue first.
Markdown and preview
The README is written in GitHub Flavored Markdown, the same format GitHub uses to show README files. Headings start with #, lists with -, and commands go in code blocks fenced by three backticks so they keep their spacing. Switch the view to Preview to see roughly how the formatted README will look before you copy it. You can keep editing the downloaded file in any text editor to add screenshots, badges or extra sections.
Keeping it up to date
Treat the README as part of the project. When you change install steps, rename a command or add a feature, update the README in the same change so the instructions always match the code. Because the generator saves your answers in this browser, you can come back, adjust a section and download a fresh README.md.
Common mistakes
- No install or usage steps. Visitors can't get started.
- Out-of-date commands that no longer work.
- No license, which leaves others unsure whether they may use the code.
- Walls of text. Use short sections and lists.
What next
Use this often? Add README to your Home screen.
Frequently asked questions
How does the README generator work?
You fill in your project details and it writes a README.md in Markdown with sections for about, features, installation, usage, help, contributing, license and author.
What should a README include?
What the project does, why it's useful, how to get started, where to get help and who maintains it.
Where should I save README.md?
In the repository's root, .github or docs folder; GitHub shows it to visitors automatically.
Does it create a LICENSE file?
No. It adds a License section; add a LICENSE file with the full license text separately.
Is my README saved?
Yes, in this browser only. Nothing is uploaded.
Was this tool helpful?
What went wrong?
We only receive the reason you pick, never what you typed into the tool.
Thanks for your feedback.