⌘ K
title · badges · install · usage · API · license

Generate a GitHub README

Fill in the fields, get a polished README.md ready to drop into your repo. Badges from Shields.io included.

README Generator
README
436 B
34 lines
Sections
6
enabled
Badges
1
shields.io
License
MIT
no author
input · fields
output · README.md
# my-project

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> A short description of what this project does.

## Features

- Feature one
- Feature two
- Feature three

## Installation

```bash
npm install my-project
```

## Usage

```js
import myProject from "my-project";

myProject.hello();
```

## Contributing

Contributions are welcome! Please open an issue or pull request.

## License

[MIT](LICENSE)
Quick Start

How to generate a README

Fill the form fields, watch the README.md update live, copy or download when done.

  1. 01

    Project basics

    Fill in the project name, a one-sentence description, the canonical install command (npm install, pip install, cargo add, brew install), and the author for the copyright line.

    The name flows into the H1 title, the Shields.io badge URLs (npm, GitHub stars, CI), and the install fence. Keep it lowercase and hyphenated to match registry conventions.

    Description appears under the title as a blockquote — write it like a tagline: what it does in 10 words or fewer.

    H1 titletaglineinstall commandauthorregistry-safe naming
    input · project basics4 fields
    my-project
    10 B · 1 lineregistry-safe · loaded
  2. 02

    Pick badges

    Toggle between four Shields.io badges: npm version (live from the registry), License (uses your selected SPDX identifier), GitHub stars (social proof), and CI status (badge from your .github/workflows/ci.yml).

    Badge URLs are built deterministically from the project name — no API keys, no signup. They re-render on every README load so they always reflect current state.

    Need a custom one (Codecov, npm downloads, Discord)? Use Markdown Badge Generator and paste alongside.

    Shields.ionpm versionSemVerCI badgesocial proof
    shields.io · 4 optionslive SVG
    [![npm](…)](…)
    15 B · 1 badgeShields.io · selected
  3. 03

    Features + usage + API

    Three Markdown sections do the heavy lifting: a Features bullet list (three to seven items, lead with verbs), a Usage block fenced as ```js with a minimal working example, and an optional API Reference in Markdown (headings + signatures).

    Empty fields are skipped silently — no "TBD" or "coming soon" placeholders in the output. Toggle Contributing off if it's a private repo.

    Want a table of contents on top? Pipe the result through Markdown TOC Generator.

    GFM bullet listfenced code## API Referenceskip-if-emptyTOC-ready
    body · features + usageGFM
    ## Features
- ⚡ Fast
    23 B · 2 linesGFM · filled
  4. 04

    Copy README

    One click copies the full README.md to your clipboard, or download for your repo root. The output uses SemVer-aware badge URLs and an SPDX-compliant license line (MIT, Apache-2.0, ISC, etc.) so GitHub's license detector picks it up automatically.

    Next steps: pair with CONTRIBUTING.md Generator, Changelog Generator, and a license file via your repo host.

    Everything runs locally — open DevTools → Network to verify zero outbound requests.

    README.mdSemVerSPDX licenseMIT / Apache-2.0privacy-first
    export · README.mdready
    ✓ Copied README
    ready to shipSPDX · success
Pro tips

Author Markdown that renders everywhere

GFM is the safe default

GitHub-Flavored Markdown is the de-facto baseline (tables, task lists, strikethrough). CommonMark is stricter but ubiquitous as a fallback.

Soft-break behaviour varies

A single newline is a space in CommonMark, a <br> in GFM. Toggle soft breaks when source matters.

Escape inside code fences

Backticks inside fenced blocks need a longer fence — three becomes four. Use ~~~ if your content has many backticks.

Anchors are slugified

GitHub lowercases, strips punctuation, and joins with hyphens. Duplicate headings get -1, -2 suffixes.

Tables need a header row

The dash row sets alignment (:---, :-:, ---:). Use Table Aligner for diff-friendly columns.

Front matter is YAML

Triple-dash blocks at the top of files are parsed by static-site generators. Use the Front-Matter Validator to catch syntax errors.

Related toolsProfile READMEBadge GeneratorCONTRIBUTING.mdChangelogTOCCheatsheet
Use Cases

When to generate a README

New repos, internal libs, project starters.

Open-source repo

Get to a polished README without copy-pasting from another project. Render path uses marked with GFM extensions enabled (tables, task lists, strikethrough, autolinks), so what you preview matches what GitHub publishes bit-for-bit. Soft-break behaviour is configurable for chat-style vs prose Markdown.

GFM-compliant

Internal libraries

Even private repos benefit from a clean README. Pairs cleanly with the Markdown Cheatsheet for syntax you can't quite remember — callout blocks, footnotes, definition lists. Output stays diff-friendly so style-only changes don't drown out real edits in PRs.

GitHub-perfect

Hackathon projects

Ship a polished entry in minutes. Cross-platform safe: anchors, code fences, and tables behave identically on GitHub, GitLab, Bitbucket, and Gitea. Heading-anchor slugs follow GitHub's lowercase-and-hyphenate rules so deep links survive a docs migration.

diff-friendly

Project templates

Drop into a yeoman-style template. No server roundtrip — perfect for proprietary content you can't paste into a public tool. The full marked + GFM bundle ships with the page, so it works offline once loaded.

render-stable

Audit pass

Reformat an inconsistent README quickly. Front matter (YAML / TOML / JSON) passes through unchanged so static-site pipelines (Jekyll, Hugo, Astro, Eleventy) read it correctly. Pair with the Front-Matter Validator to catch syntax errors before deploy.

cross-platform

Education

Show students the standard README structure. Output is reproducible: identical input always produces identical Markdown, so doc-generation scripts can rely on it for snapshot tests and embedded into release workflows.

SEO-friendly
FAQ

Frequently asked questions

Toggle Contributing on/off; leave fields blank to skip sections (e.g. blank Usage hides the section).
Coming soon. For now use the dedicated Markdown Badge Generator and paste output.
Shields.io — they format using the project name and license you provided.
Add them to the Usage textarea separated by blank lines.
No. README is built in your browser.
Suggest a tool

Something missing?

Tell us what you need. We ship the top requests every two weeks.

Sent straight to the maintainers · no account needed
47 in queue·8 shipped this month
Request queued. Thanks!