Skip to content
All posts
updated June 5, 202612 min read
github
readme
open source
markdown
gfm
guide

GitHub README Markdown: Complete Guide (Structure, GFM, Templates & Examples)

The in-depth GitHub README playbook — star-winning structure, GFM tables and alerts, Mermaid diagrams, profile READMEs, badges, CI snippets, anti-patterns, and a copy-paste template.

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.

GitHub Flavored Markdown (GFM) — what actually renders

GitHub READMEs use GFM, not plain CommonMark. The extras that matter most:

FeatureSyntaxNotes
Tables| col | pipesAlignment with :---:
Task lists- [ ] / - [x]Clickable in issues/PRs
Strikethrough~~text~~
Autolinkshttps://…No angle brackets needed
Alerts> [!NOTE]Note, Tip, Important, Warning, Caution
Footnotes[^1]Supported in READMEs
Mermaid```mermaidFlowcharts, sequence, Gantt
Syntax highlight```ts100+ languages

Validate GFM before push with the GFM checklist. For callout syntax that also works in Obsidian and docs sites, use the callout generator.

GFM alerts in READMEs

> [!NOTE]
> Useful context that readers can skip if they are in a hurry.

> [!WARNING]
> Breaking change in v2 — migration required.

> [!TIP]
> Set `NODE_ENV=production` before deploy.

Alerts render as colored blocks on GitHub — cleaner than bold paragraphs for warnings and migration notes.

Mermaid diagrams

```mermaid
flowchart TD
  A[Clone repo] --> B[Install deps]
  B --> C[Run tests]
  C --> D{Pass?}
  D -->|yes| E[Ship]
  D -->|no| F[Fix]
```

Keep diagrams under ~30 nodes — huge graphs slow README load and fail on mobile. Prototype in the diagram tools hub, then paste the fenced block.

Tables that scan well

| Plan | Requests/mo | Price |
| ---- | :---------: | ----: |
| Free | 1,000       | $0    |
| Pro  | 50,000      | $12   |

Build pipe tables in the table generator to avoid column misalignment — one missing | breaks the whole table on GitHub.

README types beyond the repo root

Library / npm package

Lead with install + one import example. Show the return value. Link to full API docs — do not dump every option in the README.

## Install

npm install your-package

## Usage

import { parse } from "your-package";
parse("# Hello"); // => ...

CLI tool

Show --help output or a 3-line demo GIF. Document the most common flags only; put the rest in docs/cli.md.

Web application

Hero screenshot above the fold. "Try it" link with no install friction. Self-host section in a <details> block for the 10% who need it.

Monorepo

Root README explains the workspace map; each package gets its own README with scoped install instructions:

## Packages

| Package | Description |
| ------- | ----------- |
| `packages/core` | Parser |
| `packages/cli` | Command line |

Link each row to the subfolder README — GitHub renders relative links correctly.

Profile README (.github special repo)

A profile README appears on your GitHub profile page, not a project repo. Create a public repo named your-username/your-username with a root README.md.

Popular sections:

  • One-line bio + current role
  • Pinned tech stack badges (keep to 4–5)
  • "What I'm working on" with links
  • GitHub stats cards (optional — many profiles skip them)
  • Blog or newsletter link

Profile READMEs support the same GFM as project READMEs — tables, alerts, Mermaid, HTML <div align="center"> for layout.

Do not duplicate your project README here. The profile is who you are; project READMEs are what the code does.

Organization README

Organizations can add a .github profile repo (orgname/.github) with a profile/README.md that renders on the org landing page. Use it for:

  • Mission statement
  • Top-level repos with one-line descriptions
  • Contributing and code of conduct links
  • Hiring or sponsorship CTAs

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 the [TOC generator](/tools/markdown-toc-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

Automating README quality

Treat the README like code — validate in CI:

  1. Link check — run the link checker on rendered HTML or use the extract links API in a GitHub Action.
  2. GFM lint — GFM checklist catches broken tables and task-list syntax.
  3. Heading structure — heading audit ensures one H1 and logical H2 flow (important for accessibility and anchor links).
  4. Reading time — estimate length with reading time so you know if the README is too long for a first visit.

Example API call for link validation in CI:

curl -X POST https://trymarkdownviewer.com/api/v1/extract/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# README\n\n[docs](./docs.md)"}'

Test requests interactively in the API playground. Full reference: API docs.

HTML in READMEs (use sparingly)

GitHub sanitizes HTML but allows a practical subset for layout:

<p align="center">
  <img src="logo.png" width="120" alt="Logo" />
</p>

<details>
  <summary>Advanced install (Docker)</summary>

  docker compose up -d
</details>

Works: align, width, details/summary, <br>, <kbd>, <sup>. Stripped or unreliable: <script>, <style>, most event handlers, custom fonts.

Prefer native GFM when possible — HTML is for alignment and collapsible sections GitHub does not offer in pure Markdown.

Link to other repo files with relative paths:

See [CONTRIBUTING.md](./CONTRIBUTING.md) and [the license](./LICENSE).

Heading anchors are auto-generated — lowercase, spaces become hyphens, punctuation dropped:

## Quick Start
[Jump to quick start](#quick-start)

After renaming headings, anchors break. Regenerate a TOC with the TOC generator when restructure is frequent.

Editing your README

Want to preview before pushing? Open the Markdown editor, paste your README, and watch the preview render the way GitHub will. Generate a TOC, lint GFM, check links, and export to HTML — all before git push.

Drafting long README sections in Obsidian or Notion? Export or copy as Markdown, then preview here to confirm GFM compatibility (especially tables, alerts, and Mermaid).

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.

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.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.