How to Write a README.md File (GitHub Markdown Guide)
Your README.md is the front door to your project. A great README communicates what your project does, who it's for, and how to get started — in under two minutes of reading. Here's how to write one that developers will actually read.
Why Your README Matters
The README.md is the first file GitHub displays when someone visits your repository. It's your project's landing page, documentation entry point, and first impression — all in one file. A poor README causes developers to move on; a great README attracts contributors, users, and collaborators.
GitHub renders README.md files as formatted HTML automatically, which means the Markdown you write becomes a polished, readable page without any extra tooling. Every heading, list, code block, table, and badge is rendered beautifully.
The Essential README Structure
A well-structured README follows a predictable pattern that developers know how to navigate. Here's the recommended structure:
# Project Name
Short description — one or two sentences explaining what this project does
and who it's for.
## Features
- Key feature 1
- Key feature 2
- Key feature 3
## Installation
\`\`\`bash
npm install your-package
\`\`\`
## Usage
\`\`\`javascript
const tool = require('your-package');
tool.doSomething();
\`\`\`
## Configuration
Explain configuration options here.
## Contributing
How to contribute to the project.
## License
MIT — see LICENSE file for details.Project Name (H1)
Use one H1 heading — the project name. Keep it clear and searchable. Avoid puns or abbreviations that require context to understand.
Description
Two to three sentences maximum. Answer: what does this project do, and who should use it? Avoid jargon. Write for someone who has never heard of your project.
Installation
Every README that involves code should have an Installation section. Use fenced code blocks with the appropriate language tag so GitHub applies syntax highlighting:
## Installation
**Prerequisites:** Node.js 18+ and npm
\`\`\`bash
# Clone the repository
git clone https://github.com/yourusername/yourproject.git
# Navigate to the directory
cd yourproject
# Install dependencies
npm install
\`\`\`Usage
Show the most common use case first, then document options. Use code blocks for all commands and code examples. If your project has a CLI, show the help output.
Contributing
Even if you don't expect contributors, include this section. It signals that contributions are welcome and sets expectations. Link to a CONTRIBUTING.md file for longer guidelines.
License
Always include a license. GitHub won't infer one from your code. The MIT license is one line and covers most open-source projects.
Markdown Syntax for README Files
GitHub uses its own Markdown flavour called GitHub Flavored Markdown (GFM), which adds some features beyond standard Markdown:
Task Lists
## Project Status
- [x] Core converter working
- [x] Unit tests passing
- [ ] Documentation complete
- [ ] v2.0 API designSyntax-Highlighted Code Blocks
\`\`\`python
def convert_markdown(text: str) -> str:
"""Convert markdown to plain text."""
return markdown_parser.render(text)
\`\`\`GitHub supports syntax highlighting for 500+ languages. Always specify the language after the opening triple backticks.
Tables
| Command | Description |
|-----------------|--------------------------------|
| `npm start` | Start the development server |
| `npm test` | Run the test suite |
| `npm run build` | Create a production build |Collapsible Sections (HTML in Markdown)
<details>
<summary>Click to expand — Advanced Configuration</summary>
Detailed configuration options here. This content is hidden by default
and revealed on click — useful for keeping your README clean.
</details>Adding Badges
Badges are small status indicators displayed at the top of your README. They communicate important metadata at a glance — build status, version, licence, test coverage, and more. All badges use the same Markdown image syntax:
Shields.io (shields.io) generates thousands of badge types. You can also create custom badges with any label, message, and colour.
Adding Screenshots and GIFs
A screenshot or GIF demo is worth a thousand words. Store images in a /docs or /.github folder in your repository and reference them with relative paths:
## Demo
<!-- Or for a GIF demo -->
Use a relative path rather than an absolute URL so the image works on all branches and forks. For GitHub Actions CI screenshots, reference the latest commit's raw image URL.
README Templates to Copy
Minimal Template
# Project Name
One-line description.
## Install
\`\`\`bash
npm install package-name
\`\`\`
## Usage
\`\`\`js
// example code here
\`\`\`
## License
MITFull Template
# Project Name
[](LICENSE)
[](https://npmjs.com/package/package)
> One-paragraph elevator pitch for your project.
## Features
- Feature 1
- Feature 2
## Installation
\`\`\`bash
npm install package-name
\`\`\`
## Usage
\`\`\`js
const pkg = require('package-name');
pkg.run();
\`\`\`
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | number | `3000` | Server port |
## Contributing
Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[MIT](LICENSE) © 2025 Your NameHow to Convert Your README to Word or PDF
Sometimes you need to share your README as a Word document or PDF — for a project brief, grant application, or documentation handoff. MDTools makes this instant:
- Markdown to Word — Copy your README.md content, paste into MDTools, download a formatted .docx
- Markdown to PDF — Export your README as a professional PDF document
All Markdown syntax including headings, tables, code blocks, and lists is preserved in the output.
FAQ
Does README.md have to be in the root directory?
For GitHub to display it on the repository page, yes — the README.md must be in the root directory (or in /docs or /.github, which GitHub also checks). You can have README files in subdirectories too; GitHub displays them when you navigate to that folder.
What is the difference between README.md and README.rst?
README.md uses Markdown; README.rst uses reStructuredText. GitHub renders both. Markdown is more widely used and easier to learn. RST is common in the Python ecosystem (particularly for Sphinx documentation). For most projects, Markdown is the better choice.
How long should a README be?
Long enough to answer the essential questions (what, who, how to install, how to use, how to contribute) and no longer. For simple packages, a single screen is ideal. For complex projects, several pages with a table of contents is appropriate. Link to separate documentation for detailed reference material rather than putting everything in the README.
Can I include HTML in a GitHub README?
Yes, GitHub allows a safe subset of HTML in README.md files — including <details>, <summary>, <br>, <table>, and most formatting tags. Some HTML attributes and JavaScript are stripped for security.