Loads a realistic starting point into the generator below. Edit anything before copying.
Project info
Badges
Features
Installation & usage
Use {package} as placeholder for project name
License & author
README.mdmarkdown
# Project Name
## Installation
```bash
npm install your-package
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the project
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
Frequently asked questions
What is a README file and why do I need one?
A README.md is the first page GitHub, GitLab, or npm show when someone lands on your project. It answers three questions at a glance: what does this do, why should I care, and how do I use it. A good README turns curious visitors into users, and a missing or weak README is the single biggest reason otherwise-solid open-source projects get ignored.
What should a good README include?
At minimum: a one-sentence description, install instructions, a short usage example, and a license. Beyond that, badges (build status, npm version, coverage) build trust, a feature list gives scanners the quick wins, a contributing section lowers the barrier for PRs, and a link to full documentation catches the people who are already convinced. Skip the wall of text — the README is a landing page, not the user manual.
Where should the README file live?
In the root of your repository, named exactly README.md. GitHub, GitLab, Bitbucket, and npm all look for that exact filename and render it as the project home page. If you have monorepo sub-packages, each package folder should also have its own README.md — npm displays the package-folder README, not the root one.
Can I use HTML inside a README.md?
Yes. GitHub's Markdown renderer allows a safe subset of HTML — <details>, <img>, <div align="center">, <br>, and basic tags all work. That's how you get collapsible sections, aligned banners, and centered logos. Avoid <script> and <style> — those are stripped for security. When Markdown alone would be awkward (e.g. a centered logo above the title), one line of HTML is the pragmatic choice.
How do badges in a README work?
Badges are just images. Most come from shields.io, which generates SVG badges from a URL like https://img.shields.io/npm/v/{package}. The image URL encodes the badge type (npm version, build status, license) and any parameters. You embed them with standard Markdown image syntax so they render on any host that supports Markdown, not just GitHub.
What Markdown syntax does GitHub support?
GitHub Flavored Markdown (GFM) — the CommonMark spec plus tables, task lists, strikethrough, autolinked URLs, fenced code blocks with syntax highlighting, and footnotes. GitHub also renders relative links, LaTeX math in dollar signs, and Mermaid diagrams inside ```mermaid code blocks. For anything more exotic — collapsible sections, aligned content, emoji reactions — you drop into HTML.
How long should a README be?
Long enough to answer 'what, why, how' and no longer. For most libraries, one to two screens is right — a description, install, one usage example, and links to full docs. If you find yourself writing a tutorial, that content belongs in a docs site, not the README. The exception is small standalone tools where the README is the docs; those can reasonably reach three to four screens.
Do I need a separate CONTRIBUTING.md file?
For small projects, a short 'Contributing' section in the README is enough. For anything expecting more than a handful of PRs, split it out — GitHub surfaces CONTRIBUTING.md automatically when someone opens a PR or issue, and separating it keeps the README focused on users, not contributors. The same logic applies to CODE_OF_CONDUCT.md and SECURITY.md.
What license should I use for an open-source project?
MIT is the default choice for most permissive libraries — short, well-understood, and compatible with almost everything. Apache-2.0 adds an explicit patent grant, which matters for enterprise adoption. GPL-3.0 keeps derivative work open-source too. If you're building a commercial product with an open-source core, look at BSL, PolyForm, or Elastic License 2.0. choosealicense.com is the canonical decision guide.
Should I add a table of contents to my README?
Only if the README is long enough to need one — roughly 300+ lines. GitHub auto-generates a floating outline for headings on the right-hand side of the file view since 2022, so a manual TOC is often redundant. If you do add one, use anchor links to your own headings (e.g. [Install](#install)) and put it right under the description, not below the badges.
How do I preview my README before pushing?
Three options. This generator shows a live preview as you type. Locally, VS Code has built-in Markdown preview (Cmd+Shift+V). And GitHub itself has a hidden preview URL — go to github.com/OWNER/REPO/blob/BRANCH/README.md and click the preview tab, or just push to a draft branch and check the render there. GitHub's own renderer is the ground truth; other tools approximate it.
When should I use a full docs site instead of a README?
Once your README passes three screens or you need search, navigation, or content that changes across versions, move the detail into a docs site and keep the README as a landing page. That's the split Stripe, Vercel, and every serious dev-tool company uses: the README says 'here's what this is, here's the install, click through for details' — the docs site does the rest. Dokly gives you that docs site in minutes.
Dokly
Want more than a README?
Dokly gives you a full docs site with MDX, search, and analytics — starting at $99/mo with a 7-day trial.