GitHub README Generator
Fill in a few fields about your project and get a well-structured README.md, ready to commit. The sections follow what visitors look for first: what the project is, how to install it and how to use it. A preview shows how it will read on GitHub.
- Runs in your browser
- No sign-up
- Free to use
How to use GitHub README Generator
- Enter the project name, a one-line description and the GitHub repository.
- Describe the project, list its features and choose how it is installed.
- Add a usage example and tick the optional sections you want.
- Check the preview, then copy the Markdown or download README.md.
GitHub README Generator features
Proven structure
Title, badges, description, contents, features, installation, usage, configuration, tests, contributing and licence.
Install commands
The right command for npm, pnpm, Yarn, pip, Composer, Cargo, Go, Docker or git clone.
Badges
Licence, stars, last commit and GitHub Actions build status, linked to your repository.
Configuration table
Turns “name | description | default” lines into a Markdown table.
Live preview
Rendered and sanitised in your browser, without loading anything from outside.
Safe output
Characters in your text that would break Markdown are escaped, and code fences adapt to their content.
When to use GitHub README Generator
- Starting a new open-source project with a complete front page.
- Replacing a one-line README on an existing repository.
- Documenting an internal tool so that colleagues can set it up alone.
- Preparing a portfolio project for recruiters to read.
GitHub README Generator FAQ
What should a README contain?
At minimum: what the project does, how to install it, and how to use it, in that order. After that, configuration, how to run the tests, how to contribute and the licence. A reader should know within ten seconds whether the project is what they need.
Where does the file go?
Save it as README.md in the root of the repository. GitHub, GitLab and most other hosts render it on the repository's front page. Package registries such as npm and PyPI also display it.
Do the badges work immediately?
The licence, stars and last-commit badges work for any public repository as soon as the README is pushed. The build badge needs a GitHub Actions workflow file; the generator assumes .github/workflows/ci.yml.
Which licence should I choose?
MIT and Apache 2.0 are permissive: anyone may use the code, including in closed products. GPL requires derived works to stay open. With no licence, others have no legal right to use the code at all. The README only names the licence; the full text has to be in a LICENSE file.
Why does the preview not show badge images?
The preview deliberately makes no requests to other servers, so images are shown as their labels. On GitHub the badges appear as images.
Can I edit the result?
Yes, and you should. The output is ordinary Markdown. Treat it as a first draft: add real examples, screenshots and the details only you know.
What makes a README useful
The README is the front door of a project. Most visitors read nothing else before deciding to use the code, contribute to it or move on. That makes it less a piece of documentation than an answer to three questions, asked in order: what is this, can I use it, and how do I start. A README that answers them near the top has done most of its job.
The opening matters most. A name and one sentence that says what the project does and for whom beats a paragraph of background. A short feature list sets expectations. Then come the installation command and the smallest example that produces a visible result, both in code blocks that can be copied. People overwhelmingly try a project by pasting the first command they see, so that command has to work on a clean machine.
Further down, the README serves people who have decided to stay. Configuration options belong in a table. The command that runs the tests tells contributors how to check their changes. A short contributing section, with a link to the issue tracker, lowers the barrier for a first pull request. The licence section states the terms under which anyone may use the code, which for many organisations decides whether they are allowed to adopt it at all.
Equally important is what to leave out. Long change histories, full API references and design discussions belong in separate files or a documentation site, linked from the README. Badges are useful in moderation: build status and licence carry information, a row of ten does not. And a README is only trustworthy while it is true, so update it in the same commit that changes the behaviour it describes.