README generator for GitHub projects and profiles
This README generator turns a short form into a clean README.md. Pick a project README or a GitHub profile README, fill in the fields, and the Markdown updates as you type. Copy it, or download a file already named README.md, and commit it to the root of your repository.
A project README follows the order readers expect: title, badges, a one-line summary, features, tech stack, installation, usage, contributing, licence and contact. Empty sections are left out, so you never ship a heading with nothing under it. The profile README is a short introduction for the special repository named after your GitHub username.
How to use the README Generator
- Choose “Project README” or “GitHub profile README”.
- Enter the name, a one-line description and the features. Add your GitHub user and repository name to unlock the build, stars and issues badges.
- Pick how people install it (npm, pip, Cargo, Go, Docker, git clone or your own commands) and paste a short usage example.
- Choose a licence and the badges you want. Switch to Preview to see the rendered result, then copy or download it.
README Generator features
Badges as shields.io links
Licence, version, build status, stars, issues, npm and PyPI badges are written as standard Markdown image links. The preview never loads them, so it makes no requests.
SPDX licence links
The licence badge and licence section link to the matching page on spdx.org, using the official identifier such as Apache-2.0 or GPL-3.0-only.
Safe live preview
The preview renders your Markdown with the open-source marked library inside a sandboxed frame that cannot run scripts or reach the network.
Table of contents
Anchors follow GitHub’s heading-link rule: lower case, spaces become hyphens, punctuation is dropped.
What belongs in a good README
- What it is in one sentence, before anything else, so a visitor can decide in seconds whether to read on.
- How to install and run it as commands that can be copied and pasted without editing.
- One real usage example. Readers learn faster from a working snippet than from a paragraph.
- Where to get help. Link the issue tracker or a contact address, and say whether pull requests are welcome, so contributors know what to do before they write any code.
- The licence. Without one, the default is that nobody may reuse the code. Add a
LICENSEfile with the full text from the SPDX licence list or choosealicense.com.
How badges work
Badge images come from shields.io. A static badge uses /badge/label-message-colour, with a literal dash written as two dashes and a space as an underscore, which is why Apache-2.0 becomes Apache--2.0. Dynamic badges such as /github/stars/OWNER/REPO or /npm/v/PACKAGE read live data, so they only work once the repository or package exists.
| Badge | URL pattern |
|---|---|
| Licence (static) | /badge/license-MIT-blue.svg |
| Build status | /github/actions/workflow/status/OWNER/REPO/ci.yml |
| Stars | /github/stars/OWNER/REPO |
| npm version | /npm/v/PACKAGE |
| PyPI version | /pypi/v/PACKAGE |
Profile README tips
GitHub shows a README on your profile when you create a public repository whose name is exactly your username and add a README.md to it. Keep it short: who you are, what you are working on, how to reach you. For Markdown you write by hand, the Markdown Formatter tidies it, and the Markdown to HTML converter shows the HTML.
README Generator FAQ
What is a README.md file?
It is a Markdown file in the root of a repository that GitHub shows on the project page. It explains what the project does and how to use it.
How do I make a GitHub profile README?
Create a public repository named exactly like your username, add a README.md to it, and GitHub displays it at the top of your profile. Choose “GitHub profile README” here to generate the text.
Does the generator upload my text?
No. The README is built in your browser. Only the optional preview loads the marked library from a CDN; your text stays on the page.
Why do the badges not show in the preview?
To keep the preview from making network requests, badge images are replaced by text chips. They appear as normal images once the README is on GitHub.
Which licence should I choose?
MIT and Apache-2.0 are permissive and common for libraries; GPL-3.0-only and AGPL-3.0-only require derived work to stay open. This tool is not legal advice; read the licence text before you decide.
Can I edit the result?
Yes. Copy the Markdown into your editor and change anything. The output is plain GitHub-flavoured Markdown.