README.md Generator

Choose your template, fill in the details, and get a professional README with live preview.

Sections

Project Details

Badges

Content

Fill in the project details to generate your README.

How to Use the README Generator

  1. Choose a template — Web App, CLI Tool, Library/Package, API, or Minimal to pre-select the right sections.
  2. Toggle sections — check or uncheck sections in the left panel to include or exclude them.
  3. Fill in project details — name, GitHub username, description, license, and npm package name for badge generation.
  4. Add content — features list, installation command, usage example, and contributing notes.
  5. Preview — see the rendered markdown in the Preview tab, or switch to the Markdown tab to see the raw text.
  6. Copy or download the finished README.md and commit it to your repository root.

What Makes a Great README?

A README is the front door of your project. It is often the first thing a potential user, contributor, or employer sees. A great README answers three questions immediately: what does this project do, why should I care, and how do I get started? According to GitHub's own research, projects with detailed READMEs receive significantly more stars, forks, and contributions than projects without them.

The Essential Sections

Every project README needs at minimum: a clear title and one-sentence description, installation instructions, and a working usage example. For open source projects, add a contributing guide and license. For APIs and libraries, a brief API reference or link to full documentation is essential. For CLI tools, show the output of --help and some example commands.

Markdown Tips for READMEs

GitHub renders Markdown with GitHub Flavored Markdown (GFM), which adds several features beyond standard Markdown. Code blocks with language identifiers get syntax highlighting: ```javascript renders colored JavaScript. Tables are supported. Task lists using - [ ] render as interactive checkboxes in issues and pull requests. Emoji shortcodes like :rocket: render as emoji. HTML is also supported for cases where Markdown syntax is not sufficient, like centering images or adding custom spacing.

Shields.io Badges

Badges from Shields.io provide at-a-glance project health indicators. The npm version badge shows the latest published version and links directly to the package page. The CI badge from GitHub Actions shows whether the latest build passed or failed. A license badge shows the license type and links to the license file. Coverage badges from Codecov or Coveralls show the percentage of code covered by tests. While badges add visual appeal, prioritize substance over badge count — a README with five badges and no usage example is worse than one with no badges and a clear example.

README Templates for Different Project Types

A web application README should lead with a screenshot or demo GIF, since visual projects benefit most from showing rather than telling. A CLI tool README should show the help output and several concrete command examples. A library README should open with a minimal working code snippet — users want to know immediately what the API looks like. An API documentation README should list endpoints, authentication methods, and include a curl example. For all types, keep the installation section as short as possible. Use the License Picker to choose the right license for your project.

Frequently Asked Questions

A good README should include: project title and description, badges showing build status and version, a features list, installation instructions, usage examples with code blocks, API documentation if applicable, contributing guidelines, and a license section. The goal is to answer 'what does it do?' and 'how do I use it?' within the first screen.
Badges are small SVG images showing real-time metadata like build status, npm version, and license. Shields.io generates badges from URL patterns. This generator creates the badge markdown automatically based on your project name and GitHub username.
Create anchor links manually: each heading gets an anchor based on its text. '## Installation' gets #installation. Create a TOC with [Installation](#installation). GitHub also auto-generates a floating TOC button for READMEs, so manual TOC sections are often unnecessary.
Use README.md. Both extensions work, but .md is the universal convention for GitHub, GitLab, npm, and all version control platforms. GitHub specifically looks for README.md to display as the repository landing page.
No. This README generator runs entirely in your browser. No project names, descriptions, or code is sent to any server. All markdown generation and preview rendering happens locally using JavaScript.