How to Write a Great GitHub README (With Template & Examples)

A README is the front page of your repo — the first impression for every visitor, recruiter, and potential contributor. A great README turns drive-by visitors into stars, contributors, and users. A bad one sends them straight to a competitor.

This guide is the full playbook: structure, badges, screenshots, the patterns the most-starred repos on GitHub use, and a copy-pasteable template at the bottom.

What a great GitHub README does

A great README answers four questions in the first 30 seconds:

1. What is this? — In one sentence.
2. Why should I care? — Three concrete benefits.
3. What does it look like? — A screenshot or animated demo.
4. How do I try it? — A copy-pasteable install or quickstart.

Anything else (architecture diagrams, contribution guides, sponsor lists) goes later — it's important, but it's not the hook.

The structure that wins stars

After analyzing the top 100 starred repos on GitHub, the high-conversion structure looks like this:

1. Project name as an H1
2. One-line tagline — what the project does
3. Badge row — version, build status, license
4. Hero shot — screenshot, GIF, or video
5. Features — bulleted list, 3–7 items
6. Quick start — install + first command
7. Usage examples — 2–4 short snippets
8. Documentation links
9. Contributing
10. License

You can rearrange, but those nine sections cover 95% of what a reader needs.

The title and tagline

The title is straightforward — your project's name as an H1:

# Markdown Viewer

The tagline immediately under it is the most important sentence in the entire README. It must answer "what is this?" in plain language. Avoid jargon. Avoid your project name (you just wrote it). Be specific.

# Markdown Viewer

A fast, secure, SEO-optimized Markdown editor and viewer with live preview.

A weak tagline:

# MyTool

Tools for the modern web developer.

(What does "for the modern web developer" mean? Nothing.)

A strong tagline:

# Astro

The web framework for content-driven websites.

(Specific. Memorable. Names the audience.)

Badge row — the credibility line

Badges show health metrics at a glance: version, build status, license, downloads. Use Shields.io — it generates badges for hundreds of services.

[![Version](https://img.shields.io/npm/v/markdown-viewer)](https://www.npmjs.com/package/markdown-viewer)
[![Build](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)](https://github.com/user/repo/actions)
[![License](https://img.shields.io/github/license/user/repo)](LICENSE)
[![Stars](https://img.shields.io/github/stars/user/repo?style=social)](https://github.com/user/repo)

Three rules:

• Maximum 5 badges. More looks like a NASCAR car.
• Make them clickable. Each badge should link to the relevant thing.
• Only include green ones. A red CI badge is worse than no badge.

Hero shot — your most underrated tool

The single best thing you can add to a README is a picture or animation showing what the project does. Visitors decide in 2–3 seconds whether to keep reading; a strong visual buys you another 30 seconds.

Options, in order of impact:

1. Animated GIF — shows the tool in motion. Keep under 5MB.
2. Annotated screenshot — labels and arrows showing key features.
3. MP4 video — GitHub supports <video> natively in READMEs.
4. Plain screenshot — better than nothing.

<p align="center">
  <img src="docs/screenshot.png" alt="Markdown Viewer running in a browser" width="800">
</p>

For animations, use terminalizer, vhs, or peek to record terminal demos, and LICEcap, Kap, or your OS screen recorder for GUI demos.

Features section — the elevator pitch

Three to seven bullets. Each starts with a verb or noun phrase. Be specific.

## Features

- ⚡ **Real-time preview** — your Markdown renders as you type
- 🎨 **150+ language syntax highlighting** via highlight.js
- 📐 **Math and diagrams** with KaTeX and Mermaid
- 🔒 **Privacy-first** — your content never leaves your browser
- 📥 **One-click export** to HTML, PDF, or printable view
- ⌨️ **Vim-style keyboard shortcuts** for power users
- 🌗 **Dark mode** with system theme detection

Why this works:

• Emojis act as visual anchors — readers skim them as icons.
• The bold part is the headline, the rest is supporting detail.
• Each bullet hints at a problem solved, not just a feature.

Don't list every feature. List the ones that differentiate your project from alternatives.

Quick start — get the user to "it works"

The quick start has one job: take a reader from zero to "it works on my machine" in under 60 seconds. The fewer steps, the better.

For a CLI:

## Quick start

```bash
npm install -g markdown-viewer
markdown-viewer my-document.md

For a web app:

```md
## Try it

Visit [markdownviewer.com](https://trymarkdownviewer.com) — no install, no signup.

For a library:

## Install

```bash
npm install @markdown-viewer/core

import { parse } from "@markdown-viewer/core";

console.log(parse("# Hello"));
// "<h1>Hello</h1>"

Hide the long-form "advanced installation" sections behind a `<details>` block — they're for the 5% of users who need them.

## Usage examples — show, don't tell

The best READMEs include 2–4 short, **realistic** usage examples. Real examples > contrived ones:

````md
## Usage

### Render a document

```ts
import { render } from "markdown-viewer";

const html = await render("# Hello, world!");

With custom plugins

import { render } from "markdown-viewer";
import { codeBlocks, math } from "markdown-viewer/plugins";

const html = await render(source, {
  plugins: [codeBlocks(), math()],
});

Show the **happy path** first. Edge cases go in the docs, not the README.

## Documentation links

If your project is more than a single function, link out to deeper docs:

```md
## Documentation

- [Getting started](https://docs.example.com/getting-started)
- [API reference](https://docs.example.com/api)
- [Examples](https://docs.example.com/examples)
```

Keep the README **scannable**. Don't try to fit a 30-page manual into it.

## Contributing section

Three lines is fine. Long contributor guides go into `CONTRIBUTING.md`:

```md
## Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup and PR guidelines.

If you'd like to discuss a feature before building, open a [discussion](https://github.com/user/repo/discussions).
```

## License

Always include a license section, even if it's just one line:

```md
## License

[MIT](./LICENSE) © 2025 Your Name
```

For commercial projects, link to the license file and mention the license name. Lawyers (and your future self) will thank you.

## Optional but valuable sections

### Table of contents

Useful for READMEs over ~10 sections. Most readers won't scroll, so put it after the hero shot.

```md
## Table of contents

- [Features](#features)
- [Quick start](#quick-start)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
```

Use [Markdown Viewer's TOC generator](/tools/markdown-table-generator) (or any auto-TOC tool) to keep this in sync.

### Comparison table

If your project competes with well-known alternatives, include a comparison. Be **fair**:

```md
| Feature           | Markdown Viewer | Tool A | Tool B |
| ----------------- | :-------------: | :----: | :----: |
| Live preview      |       ✅        |   ✅   |   ❌   |
| Math support      |       ✅        |   ❌   |   ✅   |
| No signup         |       ✅        |   ❌   |   ✅   |
| Privacy-first     |       ✅        |   ❌   |   ❌   |
```

A real, balanced comparison earns trust. A fake one (where you "win" everything) destroys it.

### Sponsors / Acknowledgments

If you have backers or used third-party libraries that deserve credit:

```md
## Acknowledgments

Built with [react-markdown](https://github.com/remarkjs/react-markdown),
[highlight.js](https://highlightjs.org), and [Tailwind CSS](https://tailwindcss.com).
```

### FAQ

A few common questions, especially for libraries with unusual design choices:

```md
## FAQ

**Why ESM-only?** … Reasons.

**Does it work in the browser?** Yes — and Node 18+.
```

## The README template (copy & paste)

Here's a battle-tested template you can adapt. Copy it into a new file, fill in the bracketed sections, and you have a solid README in 15 minutes.

````md
<h1 align="center">
  <img src=".github/logo.svg" alt="" width="80" />
  <br>
  Project Name
</h1>

<p align="center">
  <strong>One-line tagline that explains what the project does.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/your-package">
    <img src="https://img.shields.io/npm/v/your-package" alt="npm version" />
  </a>
  <a href="https://github.com/user/repo/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml" alt="Build status" />
  </a>
  <a href="./LICENSE">
    <img src="https://img.shields.io/github/license/user/repo" alt="License" />
  </a>
</p>

<p align="center">
  <img src=".github/screenshot.png" alt="A screenshot of the app" width="800" />
</p>

## Features

- 🚀 **Headline feature** — one sentence explaining the value
- 🎨 **Another feature** — keep these specific
- 🔒 **Privacy/security** — if relevant
- 📦 **Distribution** — npm? CLI? Web app? Note it
- ⚡ **Performance** — measurable claims when you can

## Quick start

```bash
# Install
npm install your-package

# Use
your-package --help
```

## Usage

### Basic

```ts
import { something } from "your-package";

something("input");
// "expected output"
```

### Advanced

See the [documentation](https://docs.example.com) for the full API.

## Documentation

- [Getting started](https://docs.example.com/getting-started)
- [API reference](https://docs.example.com/api)
- [Examples](https://github.com/user/repo/tree/main/examples)

## Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

[MIT](./LICENSE) © 2025 Your Name

Editing your README

Want to preview before pushing? Open the Markdown editor, paste your README, and watch the preview render exactly the way GitHub will. You can also generate a TOC, lint for common issues, and export to clean HTML.

README anti-patterns

Things that make readers bounce:

1. No screenshots. If a visual product has no image, visitors leave.
2. Roadmap as the third section. Save it for the bottom — readers don't care yet.
3. "Coming soon" everywhere. Ship features, then write about them.
4. Wall-of-text features section. Use bullets. White space is your friend.
5. Outdated install instructions. Test the quick start on a fresh machine before every release.
6. Marketing-speak. "Revolutionary", "blazingly fast", "best-in-class". Show, don't claim.
7. 15 badges in two rows. Five max.
8. Tone shifts mid-document. Pick a voice (formal, casual) and stick to it.

Maintenance: a README is a living document

The README that wins your first 1,000 stars is not the same README that wins your next 10,000. Revisit it:

• After every major release — the install command might have changed.
• After every contributor wave — what questions did people ask? Add them as FAQ entries.
• When the project's purpose evolves — your tagline should reflect what it is, not what it was.

A great README is the highest-leverage 30 minutes you'll spend on your project this month.

Related articles

• Markdown cheat sheet — every Markdown feature on one page
• Markdown table guide — for comparison tables
• How to add images in Markdown — for screenshots and logos
• Best Markdown editors — write your README somewhere comfortable

Try the editor

Open the Markdown editor to draft your next README with live preview, autosave, link checker, and one-click export. It renders Markdown the same way GitHub does — what you see is what your visitors will see.