How to Write a Good README.md

The first thing anyone sees in a GitHub project is its README.md. A good README tells people in 30 seconds what the project is, how to install it and how to use it. This guide covers the standard structure, the Markdown you'll use most and a template you can copy.

To write while you read, open the online Markdown editor: type on the left, see the result on the right.

What should a README include?

A solid README usually has, in order:

  1. Project name and a one-line summary – what problem it solves.
  2. A screenshot or demo – a picture says more than paragraphs.
  3. Features – three to six key points.
  4. Installation – commands people can copy and run.
  5. Usage – the simplest working example.
  6. Configuration – environment variables or config files, if any.
  7. Contributing – how to report issues and submit changes.
  8. License – for example MIT or Apache-2.0.

For small projects, sections 1, 4, 5 and 8 are enough. The goal is to get a first-time visitor up and running.

Markdown you'll use most

Title and summary

# Moread

> A Markdown viewer that needs no install and never uploads your files.

Use a single # title and ## for sections. For the full syntax, see the Markdown syntax guide.

Installation commands in code blocks

```bash
git clone https://github.com/you/project.git
cd project
npm install
```

Adding the language (bash, python, javascript) gives you syntax highlighting on GitHub.

Screenshots

![Main screen](docs/screenshot.png)

Keep images in a docs/ or assets/ folder and use relative paths so they don't break when the project moves.

Badges

Many READMEs start with a row of badges for version, license or build status:

![License](https://img.shields.io/badge/license-MIT-green)

Badges are a nice touch, but a few are plenty.

Tables for options

| Option | Default | Description |
| --- | --- | --- |
| `port` | `3000` | Server port |
| `debug` | `false` | Show debug output |

More table tips are in the Markdown table guide.

Architecture diagrams with Mermaid

GitHub supports Mermaid, so you can draw diagrams right in your README:

flowchart LR
    A[User] --> B[Frontend] --> C[API] --> D[Database]

See the Mermaid diagram guide for details.

README template (copy and paste)

# Project name

One sentence about the problem this project solves.

![Screenshot](docs/screenshot.png)

## Features

- Feature one
- Feature two
- Feature three

## Installation

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

## Usage

```javascript
import { hello } from 'your-package';
hello('world');
```

## Configuration

| Option | Default | Description |
| --- | --- | --- |
| `option` | `true` | What this option does |

## Contributing

Issues and pull requests are welcome.

## License

MIT

Paste the template into the online editor, fill in your details and press Ctrl + S to download it as README.md.

Tips for a better README

  • Lead with "how to run it" – most visitors just want to install and try it.
  • Make commands copy-pasteable – keep explanations out of the command lines.
  • Keep it current – when the code changes, update the README.
  • Add a table of contents for long READMEs.
  • Offer translations such as README.ja.md and link them at the top.

When you're done, drop README.md into Moread to check that headings, tables and diagrams look right before you push.