How to Write a README File in Markdown

A README is usually the first thing anyone sees when they land on a project, and it's read fast — skimmed for the answer to "what is this and how do I use it," not read start to finish like an essay. Markdown's structure (headings, lists, code blocks) fits that skim-first reality well.

A structure that works for most projects

# Project Name

One sentence describing what this does.

## Installation

Step-by-step commands.

## Usage

A basic example.

## Configuration

Options someone might need to change.

## License

One line.

Not every section applies to every project — a small script doesn't need a "Configuration" section if there's nothing to configure. Cut what doesn't apply rather than padding it out.

The parts people actually read

The one-sentence description right under the title and the first code block under "Usage" get read far more often than anything else. If someone only reads two things in your README, make sure those two things answer "what is this" and "how do I run it."

Formatting choices that help

• Use fenced code blocks (triple backticks) for every command — it lets people copy-paste without picking up stray formatting.
• Keep headings short and literal ("Installation," not "Getting Started on Your Journey").
• A single badge or two (build status, license) near the top is useful; a wall of ten badges usually isn't.

Checking it before you commit it

Paste your draft into the Markdown to HTML tool to see it rendered exactly as GitHub or GitLab would show it, before you push — catching a broken list or a misplaced code fence takes five seconds this way instead of a commit-and-check round trip.

Frequently asked questions

Does the file have to be named exactly README.md?

For GitHub, GitLab, and most code hosts to display it automatically on the repository page, yes — the capitalization and .md extension both matter.