How to Write a Great README in Markdown
A great README answers five questions fast: what the project does, why it's useful, how to start, where to get help, and who maintains it. Write it in Markdown so it stays plain text, renders anywhere, and is readable even before it's rendered.
Quick answer
Open with a one-line description, then add only the sections a newcomer needs: install, usage with a real example, and how to contribute. Format it with Markdown — ## headings for structure, fenced code blocks for commands and code, and links for anything you reference. Keep it short enough that someone can skim it in a minute, and keep it in the repo so it's versioned with the code.
What a README is for
The README is usually the first thing a visitor reads, so it sets expectations for the whole project. GitHub suggests it cover five things: what the project does, why it's useful, how to get started, where to get help, and who maintains and contributes (GitHub Docs). If a reader can answer those five questions in a minute, the README is doing its job.
Name the file README.md and put it in the project's top-level directory — that's where new readers land, and code hosts display it automatically (Make a README). The name is traditionally uppercase so it stands out next to your source files.
The sections worth including
Every project is different, so treat these as a menu, not a checklist. Most projects want a subset of the following.
Name and description
Lead with a self-explaining name and a sentence or two on what the project does specifically. If there are close alternatives, this is the place to note what makes yours different.
Installation
List the exact steps. Assume the reader is new to the project and wants to get running with no guesswork. If it needs a particular language version or operating system, add a short requirements note.
Usage
Show the smallest example that actually demonstrates the project, and include the expected output when you can. A three-line example a reader can copy beats a paragraph describing what the code would do.
Support, contributing, and license
Tell people where to get help — an issue tracker, a chat, an email. State whether you accept contributions and how. And for open-source projects, say how the work is licensed. Splitting contribution rules into a separate CONTRIBUTING.md is a common move; on GitHub, anyone opening an issue or pull request then gets a link to it (Make a README).
Format it with Markdown that renders everywhere
Markdown is the standard README format because it's plain text with lightweight formatting, and it's specified — CommonMark gives it an unambiguous definition and a reference implementation (CommonMark). GitHub renders GitHub Flavored Markdown, a superset of CommonMark that adds tables, task lists, and more (GFM spec).
Headings and a free table of contents
Headings use number signs — one for #, two for ##, up to six — with a space after the signs. In a README the title is usually the project name as a top-level heading, then ## for major sections and ### for subsections. Structure pays off twice: GitHub auto-generates a table of contents from your section headings, reachable from the Outline menu on the rendered page (GitHub Docs).
Fenced code blocks with syntax highlighting
Wrap commands and code in a fenced code block — at least three backticks to open and close. The first word after the opening fence is the language identifier, which turns on syntax highlighting:
npm install your-packageimport { greet } from "your-package";
greet("world"); // "hello, world"The text inside a fence is literal, so your code is shown exactly as written. Picking the right language tag (bash, js, python) is what gets you readable, colorized samples (GitHub Docs).
Links that keep working
Links use [text](url). Three kinds show up in a README. Anchor links jump to a heading in the same file, like [Usage](#usage) — GitHub builds the anchor from the heading text. External links point to docs and references. And relative links point to other files in your repo, like [Contributing](CONTRIBUTING.md). Prefer relative links for in-repo files: GitHub rewrites them for the current branch, and they keep working when someone clones the repo, where absolute links often break (GitHub Docs).
Keep it short, keep it current
A README should hold only what someone needs to get started and contribute; deeper material belongs in a wiki or a docs site (GitHub Docs). That said, too long beats too short — if it's getting big, move sections into other docs rather than deleting information (Make a README).
Because the README lives in the repository, it's versioned with your code: Git records changes over time so you can compare or recover earlier versions (Pro Git). Update it in the same commit as the change it describes, and it stays trustworthy. For more on keeping plain-text files portable, see our other guides.
Writing your README with Carets
Carets is a fast, native notes and code editor for iPhone, iPad, and Mac, and it fits README writing because a README is just a Markdown file. You get Markdown editing with syntax highlighting, so a fenced bash or js block reads the same way it will on GitHub, and your file stays plain text and portable — yours to move into any repo. Files, projects, and tags keep a README draft next to the project it belongs to, and because Carets is native rather than a web wrapper, editing on your phone is as quick as on your Mac. When you want to tighten a README on the go and have it render cleanly the moment you paste it into your repo, Carets is the place to write it. Carets is available on the App Store for iPhone, iPad, and Mac. For more Markdown and code workflows, browse the Carets articles index.
FAQ
Where should the README file live?
In the project's top-level directory, named README.md. GitHub also recognizes a README in the .github or docs directory, checking .github, then the root, then docs (GitHub Docs).
How long should a README be?
Long enough to cover getting started and contributing, short enough to skim. If it grows past that, move the extra detail into a wiki or docs site rather than cutting useful information (Make a README).
How do I add syntax highlighting to a code block?
Open a fenced code block with at least three backticks and put the language identifier right after the fence, such as python or bash. The first word of the info string sets the grammar the renderer uses (GFM spec).
Why use relative links in a README?
Relative links to other files in your repo keep working across branches and in clones, because GitHub rewrites them for the current branch; absolute links may break when the repo is cloned (GitHub Docs).