README Markdown: How to Write a Great README
May 6, 2026 · 6 min read
README Markdown Guide: Write a Great GitHub README
A README markdown file is the front page of every GitHub repository. It tells visitors what your project does, how to install it, and how to contribute. A well-written README increases stars, contributions, and adoption. This guide covers the essential sections, formatting best practices, and a starter template you can use today.
What Is a README.md File?
A README.md file is a markdown document that GitHub automatically renders on your repository's main page. The .md extension tells GitHub to parse it as markdown and display formatted content with headings, code blocks, badges, images, and tables. Every open-source project, internal tool, and code library benefits from a clear README.
GitHub displays the README below the file listing on the repository page. It is the first thing visitors see, and research by GitHub shows that repositories with detailed READMEs receive 30% more stars on average compared to those with minimal documentation.
Essential Sections of a README
A complete README includes these sections in order:
Project Title and Description
Start with an H1 heading matching your project name, followed by a one-paragraph description (2 to 3 sentences). Include what the project does, who it is for, and what makes it different.
# ProjectName
A fast, lightweight markdown editor for the terminal. Built for developers who prefer keyboard-driven workflows over GUI editors. Supports live preview, syntax highlighting, and export to PDF.
Badges
Badges show build status, version, license, and download counts at a glance. Place them directly below the description:
Use shields.io to generate badge URLs. Keep badges to 3 to 5 for a clean look.
Table of Contents
For READMEs longer than 5 sections, add a table of contents with anchor links:
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)
GitHub auto-generates heading IDs, so ## Installation gets the anchor #installation. See our markdown table of contents guide for more details.
Installation
Provide copy-paste-ready install commands. Show the primary method first, then alternatives:
## Installation
```bash
npm install my-package
```
Or with yarn:
```bash
yarn add my-package
```
Include prerequisites (Node.js version, Python version, OS requirements) before the install command if they are not obvious.
Usage
Show a minimal working example. Developers want to see the shortest path from installation to a working result:
## Usage
```javascript
import { convert } from 'my-package';
const result = convert('# Hello World');
console.log(result); // <h1>Hello World</h1>
Follow the minimal example with more advanced use cases if relevant. Use separate H3 subsections for different features.
### Configuration
Document available options in a table:
```markdown
## Configuration
| Option | Type | Default | Description |
|---|---|---|---|
| `theme` | string | `"light"` | Editor color theme |
| `lineNumbers` | boolean | `true` | Show line numbers |
| `fontSize` | number | `14` | Font size in pixels |
Tables are the clearest way to document options. See our markdown table guide for formatting tips.
Contributing
Encourage contributions with clear instructions:
## Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a pull request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
License
State the license clearly at the bottom:
## License
Distributed under the MIT License. See `LICENSE` for more information.
Advanced README Features
Screenshots and GIFs
A screenshot is worth a thousand words of documentation. Show your project in action:
## Screenshots
For GIFs, use tools like LICEcap (Windows/macOS) or Peek (Linux) to record short demonstrations. Keep GIFs under 10 seconds and 5 MB.
Collapsible Sections
Hide long content behind expandable sections to keep the README scannable:
<details>
<summary>View all configuration options</summary>
| Option | Description |
|---|---|
| ... | ... |
</details>
See our collapsible section guide for nesting and styling tips.
Mermaid Diagrams
GitHub renders Mermaid diagrams natively. Use them for architecture overviews:
```mermaid
graph LR
A[Client] --> B[API Gateway]
B --> C[Auth Service]
B --> D[Data Service]
C --> E[Database]
D --> E
```
Check our Mermaid diagrams guide for flowcharts, sequence diagrams, and more.
README Template
Use this template to start your next README:
Ready to use this template?
Opens in the editor — sign up to save and export.
Common Mistakes in README Files
Mistake 1: No installation instructions. Developers will leave if they cannot figure out how to install your project in under 30 seconds.
Mistake 2: Outdated screenshots. If your UI has changed, update the screenshots. Outdated visuals erode trust.
Mistake 3: Wall of text. Use headings, code blocks, tables, and badges to break up content. A README should be scannable, not a novel.
Mistake 4: Missing license. Without a license, your code is technically all rights reserved. Always include a LICENSE file and reference it in the README.
Frequently Asked Questions
Summary
A README markdown file is the most important document in your repository. Include a clear description, badges, installation instructions, usage examples, and a license. Use tables for configuration, collapsible sections for long content, and Mermaid diagrams for architecture. Grab the template above to start your next project, draft it in our markdown editor, and check the markdown cheat sheet for syntax reference.
Written by the Markdown Editor Online team. Last updated May 2026.