Writing a README.md
A README is the front page of your repository — the file GitHub renders at the top of the repo page. It is the first and often only thing someone reads before deciding whether to use, contribute to, or skip your project. A good README is the single highest-leverage piece of documentation you can write.
Why every repo needs one
GitHub looks for
README.md(or.rst,.txt) at the repo root and renders it on the home page automatically. No config needed.It is the first thing search engines index.
It answers the three questions every new viewer has: What is this? Why would I use it? How do I run it?
A repo without a README looks abandoned, even if the code is great.
Anatomy of a great README
A sensible default outline
# Project Name short tagline (one line) [badges: build status | npm version | license | etc.] ## Description 2-4 sentences. What problem does this solve, for whom? ## Demo / Screenshot gif, screenshot, or link to a live site ## Installation copy-pasteable install commands ## Usage minimal "hello world" example. Then link to deeper docs. ## Configuration env vars, config file format ## Development how to clone, install deps, run tests ## Contributing link to CONTRIBUTING.md ## License MIT, Apache-2.0, etc.
Markdown — the cheat sheet you actually need
Headings, emphasis, lists
# H1 ## H2 ### H3 *italic* **bold** ~~strikethrough~~ `inline code` - bullet - bullet - nested 1. ordered 2. ordered - [x] done task - [ ] todo task
Links, images, code blocks
[link text](https://example.com)
```bash
npm install my-package
```
```js
console.log("hello")
```Tables
| Column | Description | | ------ | --------------- | | name | string, required| | port | number, default 8080 |
GitHub-flavoured extras
Alerts (newer Markdown)
> [!NOTE] > Use these for general info. > [!TIP] > For pro tips. > [!IMPORTANT] > For something the reader must not miss. > [!WARNING] > For risks. > [!CAUTION] > For potential data loss.
Collapsible sections
<details> <summary>Click to expand the full config schema</summary> ```yaml server: port: 8080 host: 0.0.0.0 ``` </details>
Mermaid diagrams render inline
```mermaid flowchart LR A[Client] -- HTTP --> B[API] B --> C[(Database)] ```
Task lists become interactive checkboxes in issues/PRs
- [x] Write tests - [ ] Add caching - [ ] Document the API
Badges
Badges are little SVG images served by shields.io (and others) that show status: build passing, latest version, license, downloads. Slot them under the H1.
Common badges
   
The profile README
Create a public repo whose name exactly matches your GitHub username. Add a README.md. That file is shown on your profile page. People use it to introduce themselves, list projects, embed stats widgets, and so on.
Bootstrap the magic repo
gh repo create jsmith --public --add-readme cd jsmith echo "# Hi, I'm jsmith" > README.md git commit -am "Profile README" git push
A minimal but complete profile README
### Hi there 👋 I'm a software engineer who works mostly with Go and TypeScript. - 🔭 Currently building: [project-name](https://github.com/jsmith/project) - 🌱 Learning: Rust, systems performance - 📫 Reach me: jsmith@example.com 
Tools that help
readme-md-generator —
npx readme-md-generatorwalks you through prompts and emits a clean README.shields.io — generate badges of every kind, copy the Markdown line.
carbon.now.sh — pretty code screenshots if you want to embed images of code rather than fenced blocks.
github-readme-stats — embed live stats widgets on your profile README.
awesome-readme — a GitHub list of exemplary READMEs to crib from.
What lives in the README vs other docs
README.md— quick orientation for a new viewer. Keep under one screen of text once you have a demo image.CONTRIBUTING.md— how to file issues, send PRs, run tests. Linked from README.CODE_OF_CONDUCT.md— community rules. GitHub will surface this in the Community tab.CHANGELOG.md— what changed in each release.SECURITY.md— how to report vulnerabilities privately./docsdirectory or external site — long-form reference material.
Common mistakes
No install command. Reader hits a wall in 30 seconds.
Wall of text with no headings. Readers skim — give them anchors.
Screenshots that are out of date. Worse than no screenshot.
Lying about the status (claiming "production ready" when the test count is 0).
Copy-pasted boilerplate that does not describe THIS project.