README Generator
Pick a template, fill in your project, reorder the sections and copy a ready README.md.
Import a README
Paste a README.md or open the file. It is cut into sections at its ## headings (never inside code blocks), so you can reorder, edit and extend it. Your current sections are replaced; you can undo.
Project details
Shown under the title. Markdown works here.
The repository for a profile README has exactly this name.
For install commands and badges. Badges need it; commands use the project name when it is empty.
What people type to run it, if it is not the package name.
Year, branch and CI workflow
In .github/workflows, for the build badge.
Sections
Tick the sections to include. Reorder them with the arrow buttons or drag the handle; open one to edit its heading and text. Italic text is template text to replace.
README.md
Checks
Loading the preview…
Images and badges are drawn as placeholders: this page loads nothing from badge services or image hosts.
About the README Generator
Build the README.md of a GitHub repository from ready-made sections — title, badges, about, features, installation, usage, configuration, API, development, contributing, licence and more — and see it rendered the way GitHub shows it while you type. Start from a template for a library, an application, a command-line tool or your GitHub profile, fill in the project details once, and the install commands, code examples, badge links and licence line are written for your ecosystem: npm, Yarn, pnpm or Bun; pip and pipx; Cargo, Go, RubyGems, Composer, NuGet, Maven or Docker.
Tick the sections you want, drag them (or use the arrow buttons) into order and edit any section’s Markdown; text you edit is kept as you wrote it. The table of contents uses GitHub’s own heading anchors, and a list of checks points out template text still to replace, badges that need more details and files your README expects in the repository. You can also import an existing README to reorder and extend it.
Badges are written as standard shields.io Markdown (and GitHub’s own workflow badge), but the preview draws them as placeholders and never loads an image, so the page makes no requests to badge services or image hosts. Everything happens in your browser; the draft is kept in this browser until you start over.
How to use it
- Choose a template: library or package, application, command-line tool, or GitHub profile.
- Fill in Project details: the name, a one-line description, the GitHub repository (owner/name or its address), the ecosystem and package name, and the licence. Commands, badge links and the licence line follow as you type.
- Under Sections, tick what you want, move sections with the arrow buttons or by dragging the handle, and open one to edit its heading and Markdown. Text in italics is template text to replace with your own.
- In the Badges section add version, build status, licence, coverage or custom badges; in a profile, tick your technologies under Tech stack.
- Read the Checks, then Copy Markdown or Download README.md, and commit the file to the root of your repository.
Examples
Package: left-pad (npm) Repository: octocat/left-pad, workflow file ci.yml License: MIT
[](https://www.npmjs.com/package/left-pad) [](https://github.com/octocat/left-pad/actions/workflows/ci.yml) [](LICENSE)
Each badge links somewhere useful: the package page, the workflow runs and the LICENSE file. The CI badge is GitHub’s own; the others are drawn by shields.io when the README is viewed.
Template: Command-line tool Ecosystem: Python (PyPI), package httpie
## Installation
With [pipx](https://pipx.pypa.io/), which installs it in its own environment:
pipx install httpie
Or with pip:
pip install httpieThe tool writes the commands in fenced ```sh blocks; a library gets pip install, and an application gets clone, virtual environment and run steps instead.
## Getting started ## API: `parse()` ## Getting started
- [Getting started](#getting-started) - [API: parse()](#api-parse) - [Getting started](#getting-started-1)
Lower case, spaces to hyphens, punctuation dropped; a repeated heading gets -1, -2 — the rules GitHub uses, so the links work there.
Tech stack: TypeScript (large badges)
The colour is the brand colour from Simple Icons and the logo is drawn white or dark grey to match the text shields.io writes on that colour.
Common uses
- Starting a new open-source project with a complete README instead of a one-line placeholder.
- Rewriting an old README: import it, reorder its sections, add the missing ones and a table of contents.
- Making a GitHub profile README with a short introduction, your tech stack as badges and your best projects.
- Getting badge Markdown right without looking up shields.io routes and escaping rules.
What a good README answers
A visitor decides in a few seconds whether a project is what they need, so the first screen matters most: the name, one sentence that says what it is and for whom, and a few badges. Then, in roughly this order:
- Why it exists and what it does well (About, Features, a screenshot or a short terminal recording).
- How to install it, with the exact command for the package manager people use.
- How to use it: the smallest complete example that works when pasted.
- How to configure it: every option with its default.
- How to help: building from source, running the tests, and how pull requests are reviewed.
- The licence, so that people know what they may do with the code.
Long reference material belongs in a docs folder or site, linked from the README.
Badges and shields.io addresses
A static badge is https://img.shields.io/badge/<label>-<message>-<colour>. In the label and message a dash is written --, an underscore __ and a space _ (or %20); other characters are percent-encoded, so 95% becomes 95%25. The colour is a shields.io name (brightgreen, green, yellow, orange, red, blue, lightgrey…), a CSS colour name or hex digits, and ?style= takes flat (the default), flat-square, plastic, for-the-badge or social (shields.io static badges).
Dynamic badges read their value when the README is viewed: /npm/v/<package>, /pypi/v/<package>, /crates/v/<crate>, /github/v/release/<owner>/<repo> and so on. Build status uses GitHub’s own badge, https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg, with ?branch= for one branch (GitHub Docs). Tech stack badges use the logo names and brand colours of Simple Icons.
GitHub Markdown in the preview
The preview renders GitHub Flavored Markdown: tables, task lists, strikethrough, autolinks and footnotes, plus what GitHub adds to it (GitHub Docs):
- Alerts: a quote whose first line is
[!NOTE],[!TIP],[!IMPORTANT],[!WARNING]or[!CAUTION]becomes a coloured callout. - Emoji shortcodes such as
:rocket:become emoji (not inside code). - Heading anchors: lower case, spaces to hyphens, other punctuation dropped, repeats numbered -1, -2.
- Raw HTML such as
<p align="center">and<details>works; like GitHub, the preview removes scripts and inline styles. - Relative links such as
LICENSEordocs/guide.mdpoint to files in the repository; with the repository filled in, the preview opens them on github.com.
GitHub shows the README in the repository’s .github folder, root or docs folder (in that order of preference) and cuts it off after 500 KiB (GitHub Docs: About READMEs).
A README for your GitHub profile
GitHub shows a README at the top of your profile when a public repository has exactly your username as its name and a non-empty README.md in its root (GitHub Docs). If such a repository existed before GitHub introduced profile READMEs, open it and press Share to profile.
The profile template has a greeting, a few lines about you, your tech stack as badges, featured projects and where to find you. Keep it short: it is the first thing people see on your profile, above your pinned repositories.
Limitations
- The preview follows GitHub’s rendering closely but is not GitHub: math (
$…$), Mermaid diagrams, maps and GitHub’s image emoji such as:octocat:are shown as written. - Images and badges are not loaded: the preview shows placeholders. Live values (latest version, build status, download counts) appear once the README is on GitHub, and only for published packages and public repositories.
- It writes the README only. Add the LICENSE file (choosealicense.com has the full texts), CONTRIBUTING.md and the other files the README links to yourself.
- Install commands and examples are the usual defaults for each ecosystem; check them against your project, especially script names such as
npm run dev. - Up to 60 sections and 300,000 characters. The draft is saved in this browser’s storage, not in an account: clearing the site’s data deletes it.
Privacy
Everything happens in your browser. What you enter or open here is not uploaded or stored by MySmartCoPilot.
Frequently asked questions
Where do I put the README?
Save it as README.md in the root of the repository (GitHub also looks in .github/ and docs/), commit and push. GitHub shows it on the repository’s front page and builds an outline of its headings.
Will the badges work on GitHub?
Yes: they are ordinary image links to shields.io, pkg.go.dev or GitHub’s workflow badge, which draw the current value each time the README is viewed. A version or download badge needs the package to be published under the name you gave (until then shields.io writes “package not found” on it); a build badge needs that workflow file in .github/workflows/, or GitHub shows it as a broken image.
Why are the badges grey boxes in the preview?
To keep your work private and the page fast, it never loads images from other sites. Each badge is drawn from its address instead: static badges with their real text and colours, live badges with a dashed outline and what they will show (version, status, count).
Does changing the project details overwrite my text?
No. A section follows the project details only until you edit it; from then on your text is kept, and the section is marked as edited. Reset to template text brings the generated text back.
Can I improve an existing README with it?
Yes. Open Import a README, paste the Markdown or open the file: it is cut into sections at its ## headings (never inside code blocks), with the # title as the project name. Every imported section keeps its text, so you can reorder them, add a table of contents and badges, and download the result.
How do the table of contents links work?
GitHub gives every heading an anchor: lower case, spaces become hyphens, other punctuation is removed and repeated headings get -1, -2. The table of contents is written with the same rules, so ## API: parse() is linked as #api-parse. It lists the ## headings after it (and ### if you choose).
Is anything uploaded?
No. The README is assembled and previewed in your browser and the draft is stored only in this browser. The page makes no requests to badge or image services, even for the badges in your README.