How to Write a GitHub README (With Examples)
The README is the first thing anyone sees when they land on your repository. A clear README gets you contributors, stars, and faster adoption. A bad one (or missing one) means people click away. This guide covers the structure, syntax, and habits that make READMEs worth reading.
Use Mizakii's Markdown Preview to write and preview your README in real time before committing it — it renders GitHub Flavored Markdown exactly as GitHub will.
Standard README Structure
Not every section is required for every project, but this is the order that works:
# Project Name
One-line description — what it does and who it's for.
## Badges (optional)
## Demo / Screenshot (optional)
## Features
## Installation
## Usage
## Configuration (if applicable)
## Contributing
## License
The Title and Description
Your H1 should be the project name. The first paragraph should answer three questions in one or two sentences:
- What does it do?
- Who is it for?
- What problem does it solve?
Bad: "This is a tool I made." Good: "A CLI tool that converts JSON files to CSV — useful for data pipelines that feed into Excel or Google Sheets."
Installation Section
Be explicit. Show the exact commands. Assume nothing about the reader's environment:
## Installation
Requires Node.js 18+.
\```bash
npm install -g my-tool
\```
Or clone and run locally:
\```bash
git clone https://github.com/username/my-tool
cd my-tool
npm install
npm start
\```
Usage Section
Show real examples — not placeholder pseudocode. If it's a CLI tool, show actual terminal output. If it's a library, show an import and a basic use case.
GitHub Flavored Markdown (GFM) Syntax
GitHub renders a superset of standard Markdown called GFM. Key features:
Tables
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value A | Value B | Value C |
| Value D | Value E | Value F |
Add colons to align columns:
|:---|— left align|:---:|— center|---:|— right align
Task Lists (checkboxes)
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
These render as interactive checkboxes on GitHub. Useful for project roadmaps and changelogs.
Strikethrough
~~deprecated feature~~
Fenced Code Blocks with Language
```javascript
const x = 1;
```
GitHub highlights syntax for 100+ languages. Always specify the language after the opening backticks.
Collapsible Sections
<details>
<summary>Click to expand</summary>
Content goes here. Can include Markdown.
</details>
Useful for long configuration examples or optional reading.
Badges
Badges are small SVG images that show build status, version, license, downloads, and more. They come from shields.io.
Common badges
Badges go right after the title, before the first section. They give visitors an instant signal of project health without reading a word.
Screenshots and GIFs
A screenshot is worth more than two paragraphs of explanation. For CLIs, a GIF showing the tool in action is even better.
Keep demo assets in a /docs folder inside the repo. Avoid hotlinking external images — they can go down.
Open Source vs Private Repo READMEs
Open source:
- Include a Contributing section (how to fork, branch, and submit PRs)
- Include a Code of Conduct link
- Be explicit about the license — put it at the bottom and link the LICENSE file
- Add a roadmap or "Planned features" section to invite contributions
Private / internal repo:
- Skip the Contributing and License sections
- Focus on setup instructions for new team members
- Add a "Who to contact" section with Slack/email handles
- Include architecture notes or link to internal docs (Notion, Confluence)
Preview Before You Commit
GitHub's web editor shows a preview tab, but it's slow to iterate in. A faster approach: paste your README into Mizakii's Markdown Preview, see the full GFM render immediately, then copy-paste back. No commit, no push, no waiting.
The editor supports:
- Tables
- Task lists
- Fenced code blocks with syntax highlighting
- Strikethrough
- Auto-linked URLs
GitHub Profile README
GitHub has a special repository: if you create a repo with the same name as your username (e.g., AliHassan/AliHassan), the README in that repo shows up on your GitHub profile page. It's your public developer bio.
A good profile README typically includes:
# Hi, I'm Ali Hassan 👋
Full-stack developer building developer tools at [Mizakii](https://www.mizakii.com).
## What I'm working on
- 🔧 Free online developer tools
- 📝 Writing about web development
## Tech stack
## Connect
[](https://linkedin.com/in/yourhandle)
Keep it short — 10–20 lines. Profile READMEs are skimmed, not read.
Common README Mistakes
No installation instructions — the most common failure. Developers land on a project, can't figure out how to run it in 30 seconds, and leave.
Installation instructions that assume context — "run npm start" without specifying required Node.js version, environment variables, or prerequisite services. Be explicit.
Only a description, no examples — a description tells people what the project does; an example shows them. Both are needed. Show a real command, a real API call, or a real screenshot.
Outdated README — a README that describes features that no longer exist, or installation steps that fail, is worse than no README. Make README updates part of your PR checklist.
No license — if there's no license, the default is "all rights reserved" — nobody can legally fork or use your code. For open source, MIT is the standard permissive choice. Add a LICENSE file and reference it in the README.
Wall of text — break up paragraphs with headings, code blocks, and lists. Most people scan, not read.
Quick Checklist
Before pushing your README:
- [ ] One-line description answers what + who + why
- [ ] Installation commands are copy-paste ready
- [ ] At least one usage example with real code
- [ ] License is stated (even if just "MIT")
- [ ] No broken image links
- [ ] Previewed in a Markdown renderer before committing