What sections should every README include?

At minimum: project name and description, installation instructions, a usage example, and license. Popular additions include badges, a demo link, configuration reference, and a contributing guide.

How do I add a CI badge to my README?

GitHub Actions provides a badge URL you can find in your workflow run. Click the three-dot menu on any workflow run and select "Create status badge" to get the Markdown snippet.

Should my README be in Markdown?

Markdown (.md) is the universal standard for READMEs on GitHub, GitLab, npm, and most other platforms. All of them render Markdown to HTML automatically.

Write a Project README in Markdown

A good README is the front door of every open-source project and sets the tone for whether developers adopt your library or move on. This template covers the essential sections: project description, badges, prerequisites, installation steps, usage examples, and a contributing guide. The Markdown previewer renders the formatted output live so you can see exactly how GitHub will display it. Adapt the badge URLs to point to your CI pipeline and npm package.

Example

# Project Name

![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)
![npm](https://img.shields.io/npm/v/your-package)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

> One-line description of what this project does.

## Prerequisites

- Node.js >= 18
- npm >= 9

## Installation

```bash
npm install your-package
```

## Usage

```js
import { yourFunction } from 'your-package';
yourFunction({ option: true });
```

## Contributing

Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT

[ open in Markdown Previewer → ]

FAQ

What sections should every README include?: At minimum: project name and description, installation instructions, a usage example, and license. Popular additions include badges, a demo link, configuration reference, and a contributing guide.
How do I add a CI badge to my README?: GitHub Actions provides a badge URL you can find in your workflow run. Click the three-dot menu on any workflow run and select "Create status badge" to get the Markdown snippet.
Should my README be in Markdown?: Markdown (.md) is the universal standard for READMEs on GitHub, GitLab, npm, and most other platforms. All of them render Markdown to HTML automatically.

Related Examples

Write a CONTRIBUTING Guide

A contributing guide reduces friction for new contributors by explaining how to ...

Write a CHANGELOG in Markdown

A structured changelog tells users what changed between versions and why, buildi...

Document a REST API in Markdown

Markdown is a practical format for lightweight API documentation that lives alon...