How to Write a README.md for Your GitHub Project
Learning how to write a README.md is one of the most practical skills for any developer. The README is the first thing people see when they visit your GitHub repository. It determines whether someone will try your project, contribute to it, or move on. Despite this, most READMEs are either missing entirely or written as an afterthought. This guide covers what to include, how to structure it, and the Markdown syntax you need.
What a README.md is and why it matters
A README.md file is a Markdown document that sits in the root of your repository. GitHub automatically renders it on the repository's main page, making it the de facto landing page for your project. The .md extension tells GitHub to parse it as Markdown and display it with proper formatting: headings, code blocks, links, and images.
A good README answers three questions immediately: What does this project do? How do I install and use it? Where do I go if I need help? If a visitor cannot answer these within 30 seconds of landing on your repo, your README needs work.
Essential sections every README needs
Not every project needs a ten-page README. But every public repository should have at least these five sections:
- —Project title and description. One or two sentences explaining what the project does and who it is for. Avoid jargon. If someone outside your team cannot understand the description, simplify it.
- —Installation. Step-by-step instructions for getting the project running locally. Include prerequisites (Node.js version, Python version, etc.), the install command, and any environment variables that need to be set. Wrap commands in code blocks so they are easy to copy.
- —Usage. Show how to actually use the project after installation. A code example, a CLI command, or a screenshot of the running application. This section turns readers into users.
- —Contributing. Even a single sentence like "Pull requests are welcome" signals that contributions are accepted. For larger projects, link to a CONTRIBUTING.md file with detailed guidelines.
- —License. State the license clearly. Many developers and companies will not use software without a declared license. A simple line like "MIT License" with a link to the LICENSE file is sufficient.
Optional but valuable sections
Depending on your project, these additional sections can make your README significantly more useful:
- —Badges. Small status indicators at the top of the README showing build status, test coverage, npm version, or license type. They provide quick visual information and signal that the project is actively maintained.
- —Screenshots or demo. For visual projects, a screenshot or GIF immediately communicates what the project looks like. Use Markdown image syntax:
. - —API reference. For libraries and packages, document the main functions, parameters, and return values. If the API is large, link to external documentation instead.
- —Changelog. A summary of notable changes in each version. For smaller projects, a section in the README works. For larger ones, use a separate CHANGELOG.md file.
- —FAQ or troubleshooting. If you repeatedly answer the same questions in issues, add them to the README. This saves time for both you and your users.
Markdown syntax tips for READMEs
GitHub-flavored Markdown supports everything you need for a professional README. Here are the elements you will use most:
One detail people often miss: GitHub renders relative links and images from the repository root. If you put screenshots in a docs/ folder, reference them as  in your README.
Example README structure
Here is a template you can copy and adapt for your own project:
This covers the essentials in under 40 lines. You can expand each section as your project grows, but starting with this skeleton gives visitors everything they need immediately.
Common README mistakes
- —No installation instructions. The single most common problem. If someone has to read your source code to figure out how to install the project, most people will leave.
- —Outdated information. A README that references old API endpoints, deprecated commands, or removed features is worse than no README. Update it when you make breaking changes.
- —Too long with no structure. A wall of text with no headings is hard to scan. Use Markdown headings to create clear sections. GitHub generates a table of contents automatically from your headings.
- —Too short. A single sentence description with no install or usage instructions tells visitors nothing. Even small projects benefit from a few paragraphs explaining what they do and how to use them.
- —Assuming context. Do not assume the reader knows your tech stack, your team, or your goals. Write the README for someone encountering the project for the first time.
Starting from existing documentation
If you already have project documentation in PDF format — perhaps a design spec, an API document, or onboarding materials — you do not have to rewrite it from scratch. Converting those PDFs to Markdown gives you a starting point that you can reshape into a proper README or a set of documentation files.
Upload your PDF to our converter, review the extracted Markdown, and pull out the sections that are relevant to your README. This is especially useful for projects that began with formal documentation before the code repository existed. Rather than maintaining two separate formats, convert everything to Markdown and keep it alongside your code in version control.