MarkdownViewer

How to Write a GitHub README in Markdown

Your README is the front door of your project. On GitHub, GitLab and npm it is the first thing a visitor sees, and it is written in GitHub-flavoured Markdown. This guide covers the structure that works, the syntax that renders reliably, and the handful of mistakes that quietly break a README after you push.

The structure that works

  1. Project name as the single # heading
  2. One or two sentences saying what the project does and who it is for
  3. Badges on the next line (build status, version, license)
  4. Installation section with the exact command
  5. Usage section with a minimal, copy-pasteable example
  6. Configuration, contributing and license sections further down

Badges in Markdown

Badges are just image links. The pattern is a linked image: [![alt](badge-url)](link-url). Services such as shields.io generate them from a URL, so a version badge can update automatically. Keep badges to a single row — a wall of them pushes the useful content below the fold.

Code blocks that render correctly

Fence every command and code sample with three backticks and add the language so GitHub highlights it. Always close the fence. An unclosed fence is the single most common README bug: everything after it — headings, links, prose — gets swallowed into one giant code block and the page looks broken.

Tables and task lists

GitHub-flavoured Markdown supports pipe tables and task lists, which are common in READMEs for compatibility matrices and roadmap checklists. Keep tables narrow and column counts consistent, since a row with the wrong number of cells will not render as a table.

Relative links and images

Links to files in the repository can be relative, such as [docs](./docs/README.md), because GitHub resolves them against the repo. Images stored in the repo work the same way. Anything the reader might open outside GitHub should use an absolute URL instead.

Preview before you push

The fastest way to catch README problems is to render it before committing. GitHub-flavoured Markdown previewing works offline in the browser, so you can paste the file, check tables, fences and links, fix anything broken, and only then commit. It saves the cleanup commit that a broken README always costs.

Frequently Asked Questions

What Markdown does GitHub use?
GitHub uses GitHub-flavoured Markdown (GFM), which is CommonMark plus tables, task lists, autolinks and strikethrough. GitLab and npm use very similar dialects, so a README written for one renders correctly on the others.
Why did my README break after pushing?
The two usual causes are an unclosed triple-backtick code fence, which swallows the rest of the file, and a table row with the wrong number of pipe-separated cells, which stops the table rendering. Both are obvious in a preview and invisible in a plain text editor.
How do I center text or images in a README?
Markdown has no alignment syntax for text. The common workaround is a small HTML block using a p tag with an align attribute or a div wrapper, since GFM passes limited raw HTML through. Use it sparingly — it is fragile if you later move the file to a stricter renderer.
Should a README be long or short?
Short enough to scan, complete enough to get started. Explain what the project is and how to run it in the first screen, then link out to fuller documentation. When a README grows past a few screens, split the detail into a docs folder and keep the README as an index.

Related Markdown Tools

Markdown ViewerMarkdown EditorREADME ViewerAll Markdown Tools