GitHub README Generator
Fill in a short form and get a clean README.md for your GitHub profile or for a project, with a live preview. Copy it or download the file when you are happy.
About you
Skills
Badges are images served by img.shields.io, a free third-party service. Anyone who opens your profile loads them from there, and they show as broken images if that service is down. Plain text lists have no such dependency.
Links
Optional extras
Enter your GitHub username above to add the stats section.
Basics
Content
Author
🔒 Your text stays in your browser. The preview shows HTML you type as plain text and never runs it.
🔒 Everything you type stays in your browser. Nothing is sent to a server.
By Shah Rukh, software developer · Last updated:
How to use the README generator
- Pick a type. A profile README is the introduction that appears at the top of your GitHub profile page. A project README is the front page of one repository.
- Fill in the form. The preview on the right updates as you type. Leave a box empty and that line or section is simply left out.
- Press Download README.md (or Copy Markdown) and add the file to your repository.
Where the file goes
Profile README
Create a public repository whose name is exactly the same as your GitHub username, for example alexmorgan/alexmorgan. Put README.md in the root of that repository. GitHub then shows it at the top of your profile.
Project README
Put README.md in the root folder of the project. GitHub renders it under the file list. Add your own LICENSE file and, if you keep the placeholder, a screenshot at docs/screenshot.png.
What each option means
| Option | What it does |
|---|---|
| Badges | Each skill becomes a small coloured image from img.shields.io. They depend on that service being online. |
| GitHub stats | Adds two image cards from the third-party github-readme-stats service. It is frequently rate-limited, so the cards can fail to load. Off by default. |
| Table of contents | A list of links to each section, using the same anchor names GitHub creates for headings. |
| Configuration | Each line becomes one table row. Separate the name, description and default value with the | character. |
| Roadmap | Each line becomes a checkbox. Start a line with [x] to show it as done. |
How heading links work on GitHub
GitHub gives every heading an anchor so you can link to it. The rule is: make the text lowercase, remove punctuation and emoji, and turn each space into a hyphen. If two headings end up with the same anchor, the second gets -1 added, the third -2, and so on.
| Heading | Anchor |
|---|---|
| Installation | #installation |
| What’s New? | #whats-new |
| ✨ Features | #-features |
| Usage (the second heading called Usage) | #usage-1 |
The emoji row surprises many people: the emoji is removed but the space after it still becomes a hyphen, so the anchor starts with one. The generator handles this for you.
A worked example: badge addresses
A static badge is just a web address. The text and colour are separated by hyphens, so shields.io needs special spellings for characters that would otherwise be confusing: a real hyphen is written twice, an underscore is written twice, and a space becomes an underscore. A licence badge for “Apache-2.0” therefore looks like this:
Tips and limits
- Characters that have a meaning in Markdown, such as
*,_,|,<and backticks, are escaped with a backslash in the text you type, so they show up as you typed them instead of changing the layout. To add your own formatting, edit the downloaded file. - Code in the installation and usage boxes is not escaped. It is placed in a fenced code block, and the fence is made longer if your code itself contains three backticks.
- The preview is close to GitHub’s rendering but not identical. Fonts, colours and emoji shortcodes may look slightly different on GitHub.
Want to tweak the finished file? Paste it into the Markdown to HTML converter to preview your edits. See also the Discord bot maker and the QR code generator.
Frequently asked questions
How do I add a README to my GitHub profile?
Create a public repository with exactly the same name as your GitHub username, then add a file called README.md to it. GitHub shows that file at the top of your profile page. Download the file from this tool and upload it there.
Is anything I type sent to a server?
No. The README is built by JavaScript in your browser. The only outside requests are optional: if you tick “Load remote images in the preview”, your browser fetches badge or stats images from img.shields.io and github-readme-stats.vercel.app.
Why do my badges or stats cards show as broken images?
Badges and stats cards are images hosted by third-party services, not by GitHub. If the service is down or rate-limited the image fails to load. Badge addresses are usually reliable; the stats cards fail more often. Switch to plain text lists if you want no dependency.
Why does the table of contents link start with a hyphen when I use emoji?
GitHub removes the emoji when it builds the anchor but keeps the space after it, and spaces become hyphens. So the heading “✨ Features” gets the anchor #-features. The generator writes the links this way so they work on GitHub.
Can I use Markdown or HTML inside the text boxes?
No. Special characters in the text boxes are escaped so they appear exactly as typed and cannot break tables or lists. To add your own formatting, links or HTML, edit the README.md file after you download it.
Which licence should I choose?
That is your decision, and this tool does not give legal advice. MIT and Apache 2.0 are common permissive choices, and GPL v3 requires that modified versions stay open source. GitHub’s choosealicense.com explains the differences. Remember to add the actual LICENSE file to your repository.
Related tools
Telegram Bot Maker
Build a Telegram bot without coding. Download ready-to-run Python.
Chrome Extension Maker
Make a site blocker, new tab page or link popup extension. No code.
Discord Embed Builder
Design Discord embeds with a live preview, JSON and discord.py code.
WhatsApp Link Generator
Make a wa.me chat link with a message, QR code and button.
Privacy Policy Generator
Answer a few questions and get a privacy policy template.
Terms & Conditions Generator
Tick the sections you need and get a terms and conditions template.