---
title: "How to Write a Great GitHub README (With Template & Examples)"
description: "A comprehensive guide to writing GitHub READMEs that win stars: structure, badges, screenshots, install instructions, and a battle-tested template you can copy."
date: "2025-11-18"
author: "Markdown Viewer Team"
tags: ["github", "readme", "open source", "markdown"]
cover: "/og.png"
---

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:

```md
# 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.

```md
# Markdown Viewer

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

A weak tagline:

```md
# MyTool

Tools for the modern web developer.
```

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

A strong tagline:

```md
# 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](https://shields.io) — it generates badges for hundreds of services.

```md
[![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.

```md
<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.

```md
## 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:

```md
## 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:

```md
## Install

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

```ts
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

```ts
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](/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](/blog/markdown-cheat-sheet) — every Markdown feature on one page
- [Markdown table guide](/blog/markdown-table-guide) — for comparison tables
- [How to add images in Markdown](/blog/markdown-images-guide) — for screenshots and logos
- [Best Markdown editors](/blog/best-markdown-editors) — write your README somewhere comfortable

## Try the editor

Open the [Markdown editor](/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.