How to Write and Preview a README.md

A README is the first thing people see in a repository, so it has to be clear and it has to render correctly. This guide gives you a simple outline to start from, the formatting rules that trip people up, and a few ways to preview the result before you commit.

What a README should answer

1. What is this project, and who is it for?
2. How do I install or run it?
3. How do I use it? Show the smallest working example.
4. How can I help, and what is the licence?

A starter outline

Copy this into the Markdown viewer and fill in your own details:

# Project name

One sentence about what it does and who it is for.

## Features
- Feature one
- Feature two

## Installation
npm install my-package

## Usage
Show the smallest working example here.

## Contributing
How to report issues and send pull requests.

## License
Name the licence and link to the LICENSE file.

Formatting mistakes that break a README

• No space after the hash: #Title is not a heading in GitHub Flavored Markdown; write # Title.
• No blank line before a list or table: leave an empty line above it or it may render as plain text.
• Broken image paths: relative paths such as docs/screenshot.png work on GitHub but not in every previewer. Check them after you push.
• Tabs mixed with spaces in nested lists can change the nesting.
• Code without a language: add a language name after the opening fence to get syntax highlighting on GitHub.

Preview before you commit

• This site: paste or open the file in the online viewer for a quick check of headings, lists, tables and code.
• GitHub's editor: when you edit a README on github.com there is a Preview tab that uses GitHub's own renderer, which is the most reliable check.
• VS Code: open the built-in preview with Ctrl or Cmd + Shift + V. See Markdown preview in VS Code.
• grip: a command-line tool that renders a local README using GitHub's rendering service, so you can check it offline from your repository before pushing.

Where previews can differ

GitHub supports a few things that most previewers, including this one, do not: alert blocks such as [!NOTE] inside a blockquote, automatic emoji codes, and diagrams written in Mermaid. If your README relies on them, confirm the result on GitHub itself.

Keep it maintained

A short README that is correct beats a long one that is out of date. When you change an install step or a command, update the README in the same commit.