Productivity, PDF & Writing

How to Write a Clear README: A Template for Every Repo (and a Linter to Check It)

A README template that answers what, why and how in the order readers need, what GitHub does with your README, and a tested Python linter that flags missing sections, untagged code blocks and broken relative links.

By Rajib Roy Published 5 min read

A README is the front door of a project. Most visitors give it a few seconds, and the question they're asking is simple: what is this, and will it solve my problem? If the answer isn't there quickly, they leave. If the install instructions are wrong, they leave angrier.

GitHub's own documentation describes a README as typically covering what the project does, why it's useful, how users can get started, where to get help, and who maintains it. That list is the skeleton of the template in this post. I also wrote a small linter that checks the mechanical parts, because a surprising number of README problems are mechanical: no description, no license, untagged code blocks, links to files that were renamed.

What GitHub does with your README

A few facts from GitHub's documentation are worth building into your habits:

  • GitHub shows the README from a hidden .github folder, the repository root or a docs folder, picking in that order if there is more than one.
  • Content beyond 500 KiB is truncated when the README is viewed on GitHub.
  • It generates a table of contents from your headings, so clear, specific headings are navigation for free.
  • Relative links are adjusted to the branch being viewed, and a link that starts with / is relative to the repository root. Link text must be on a single line, or the link breaks.
  • GitHub's advice is that a README should contain only what developers need to get started and contribute, with longer documentation in a wiki or a docs folder.

The template

The order matters. It follows the questions a reader asks, from "what is it" to "can I trust it enough to use it":

README.template.md

# Project name

One sentence: what it does and who it is for. Then one sentence on why it exists or how it differs.

<!-- badges optional: build status, version, license. Keep to three at most. -->

## Quick start

```bash
npm install project-name
```

```js
import { thing } from 'project-name';

console.log(thing('hello')); // -> "HELLO"
```

Expected output shown above. If something fails, see [Troubleshooting](#troubleshooting).

## Installation

Requirements: Node.js 20 or later (state exact versions you tested).

```bash
npm install project-name
```

## Usage

The three most common tasks, each with a runnable example.

### Do the first common thing

```js
// minimal, complete example
```

## Configuration

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `name` | string | none | Describe it in one line |

## Troubleshooting

- **Error message exactly as shown**: what it means and the fix.

## Contributing

How to run the tests: `npm test`. Link to [CONTRIBUTING.md](CONTRIBUTING.md) if longer.

## License

MIT. See [LICENSE](LICENSE).

Here is why each part is where it is:

  1. Title and two sentences

    What it does and who it is for, then what makes it different. A reader should be able to stop here and know whether to continue.

  2. Quick start before anything else

    A real, runnable example with its expected output. Show the thing working in under a minute, and the reader will forgive the rest of the page.

  3. Installation, with versions

    State the runtime versions you actually tested. "Node.js 20 or later" is useful; "a recent Node" is not.

  4. Usage by task

    The three most common tasks, each with a complete example. Keep long reference material elsewhere and link to it.

  5. Configuration as a table

    Option, type, default and a one-line description. Tables are quicker to scan than prose.

  6. Troubleshooting with the exact error text

    Search engines match error messages. Paste the message as it appears and give the fix.

  7. Contributing and license

    How to run the tests, and the license in one line. Projects without a license are legally awkward to use, so don't leave it out.

The linter

This script checks the mechanical parts: the first line is a single title, a description paragraph follows it, there are install, usage and license sections, every code block has a language tag, there are no leftover TODOs, and every relative link points to a file that exists. It ignores anything inside code fences, so an example heading in a code block doesn't count as a real one. It exits with status 1 if it finds an error, so it can run in continuous integration.

readme_lint.py

"""A small README checker: structure, runnable examples, and links that point at real files.

    python readme_lint.py path/to/README.md
Exit status 1 if any ERROR is found.
"""
import re
import sys
from pathlib import Path

SECTIONS = {
    "install": ("install", "installation", "getting started", "quick start", "quickstart", "setup"),
    "usage": ("usage", "quick start", "quickstart", "example", "examples", "how to use"),
    "license": ("license", "licence"),
}
LINK = re.compile(r"(?<!\!)\[[^\]]+\]\(([^)\s]+)\)")


def headings(text):
    return [(len(m.group(1)), m.group(2).strip()) for m in re.finditer(r"^(#{1,6})\s+(.*)$", strip_code(text), re.M)]


def strip_code(text):
    return re.sub(r"^```.*?^```", "", text, flags=re.M | re.S)


def fences(text):
    """List of (language, body) for each fenced block."""
    return [(m.group(1).strip(), m.group(2)) for m in re.finditer(r"^```([^\n]*)\n(.*?)^```", text, re.M | re.S)]


def lint(text, root="."):
    findings = []
    add = lambda sev, msg: findings.append((sev, msg))
    lines = [l for l in text.splitlines() if l.strip()]
    hs = headings(text)

    if not lines or not lines[0].startswith("# "):
        add("ERROR", "the first line should be a single # title")
    if sum(1 for lvl, _ in hs if lvl == 1) > 1:
        add("WARN", "more than one # title")

    # a plain-prose description right under the title
    body = [l for l in lines[1:6] if not l.startswith(("#", "<!--", "[!", "!["))]
    if not body or len(body[0]) < 20:
        add("ERROR", "no description paragraph directly under the title")

    names = [t.lower() for _, t in hs]
    for key, aliases in SECTIONS.items():
        if not any(any(a in n for a in aliases) for n in names):
            add("ERROR", f"no {key} section (looked for: {', '.join(aliases)})")

    blocks = fences(text)
    if not blocks:
        add("ERROR", "no code blocks: a README should show something a reader can run")
    for lang, _ in blocks:
        if not lang:
            add("WARN", "a code block has no language tag (```bash, ```js ...)")
            break

    if re.search(r"\b(TODO|FIXME|lorem ipsum)\b", strip_code(text), re.I):
        add("WARN", "leftover TODO/FIXME/placeholder text")

    for target in LINK.findall(strip_code(text)):
        if re.match(r"^(https?:|mailto:|#)", target):
            continue
        path = target.split("#")[0]
        # GitHub reads a link starting with / as relative to the repository root, so treat root as that
        if path and not (Path(root) / path.lstrip("/")).exists():
            add("ERROR", f"relative link points to a file that does not exist: {target}")

    long_lines = sum(1 for l in strip_code(text).splitlines() if len(l) > 300)
    if long_lines:
        add("WARN", f"{long_lines} very long line(s); consider breaking up the text")
    return findings


if __name__ == "__main__":
    path = Path(sys.argv[1])
    found = lint(path.read_text(), path.parent)
    for sev, msg in found:
        print(f"{sev}: {msg}")
    print("OK" if not found else f"{len(found)} finding(s)")
    sys.exit(1 if any(s == "ERROR" for s, _ in found) else 0)

Run on a deliberately poor README, it reports seven findings:

ERROR: the first line should be a single # title
ERROR: no install section (looked for: install, installation, getting started, quick start, quickstart, setup)
ERROR: no usage section (looked for: usage, quick start, quickstart, example, examples, how to use)
ERROR: no license section (looked for: license, licence)
WARN: a code block has no language tag (```bash, ```js ...)
WARN: leftover TODO/FIXME/placeholder text
ERROR: relative link points to a file that does not exist: docs/guide.md
7 finding(s)

Run on the template itself, it flags only CONTRIBUTING.md and LICENSE, because those files don't exist in my demo folder. That's correct behaviour: a link to a missing file is exactly what it should catch.

Does it work?

The tests confirm that the template passes once its linked files exist, that the bad README is flagged for each of the right reasons (and that external links are not checked), that headings and links inside code fences are ignored, and that a link starting with / is resolved from the repository root, matching GitHub's rule. All five pass.

test_readme_lint.py

import tempfile
import unittest
from pathlib import Path

from readme_lint import lint

HERE = Path(__file__).parent
BAD = """Welcome to my project!!

Some thoughts. TODO write this properly.

```
run-it
```

See [the guide](docs/guide.md) and [site](https://example.com).
"""


class Tests(unittest.TestCase):
    def test_the_template_passes_cleanly_once_its_links_exist(self):
        with tempfile.TemporaryDirectory() as tmp:
            (Path(tmp) / "CONTRIBUTING.md").write_text("x")
            (Path(tmp) / "LICENSE").write_text("x")
            self.assertEqual(lint((HERE / "README.template.md").read_text(), tmp), [])

    def test_template_reports_missing_linked_files(self):
        with tempfile.TemporaryDirectory() as tmp:
            msgs = [m for _, m in lint((HERE / "README.template.md").read_text(), tmp)]
        self.assertTrue(any("CONTRIBUTING.md" in m for m in msgs))
        self.assertTrue(any("LICENSE" in m for m in msgs))

    def test_bad_readme_is_flagged_for_the_right_reasons(self):
        with tempfile.TemporaryDirectory() as tmp:
            found = lint(BAD, tmp)
        msgs = " | ".join(m for _, m in found)
        self.assertIn("first line should be a single # title", msgs)
        self.assertIn("no install section", msgs)
        self.assertIn("no usage section", msgs)
        self.assertIn("no license section", msgs)
        self.assertIn("no language tag", msgs)
        self.assertIn("TODO", msgs)
        self.assertIn("docs/guide.md", msgs)
        self.assertNotIn("example.com", msgs)             # external links are not checked

    def test_leading_slash_means_repository_root(self):
        text = "# T\n\nA description that is long enough.\n\n## Install\n\n```bash\nx\n```\n\n## Usage\n\nSee [guide](/docs/guide.md).\n\n## License\n\nMIT\n"
        with tempfile.TemporaryDirectory() as tmp:
            self.assertTrue(any("docs/guide.md" in m for _, m in lint(text, tmp)))
            (Path(tmp) / "docs").mkdir()
            (Path(tmp) / "docs" / "guide.md").write_text("x")
            self.assertEqual(lint(text, tmp), [])

    def test_code_blocks_are_ignored_when_looking_for_headings_and_links(self):
        text = "# T\n\nA description that is long enough.\n\n## Install\n\n```bash\n# not a heading\n[x](missing.md)\n```\n\n## Usage\n\n```bash\nx\n```\n\n## License\n\nMIT\n"
        self.assertEqual(lint(text, "."), [])


if __name__ == "__main__":
    unittest.main()

An honest limit: the linter can't judge writing. A README can pass every check and still be useless if the quick start doesn't run. The only real test is to follow your own instructions on a clean machine or a fresh container, as if you'd never seen the project. Do it before each release; it's the one check no script replaces.

An exercise for the quick start

The quick start is the part that decays fastest, so test it the way a stranger would. Open a fresh container or a clean user account, follow only what the README says, and write down every moment you had to guess. Each guess is a missing line. Typical gaps are an undeclared runtime version, a step that needs a global tool, an environment variable that is never mentioned, and a command that works only from a particular folder. Fix the README, not your machine, and repeat until the commands run exactly as written. It takes about ten minutes and it is the highest-value thing you can do for a new user.

Keep it alive

A README that was right at release is wrong a few months later unless something forces a check. Put the linter in your continuous integration so that a renamed file or a deleted section fails the build, and add the README to your release checklist. Treat a confusing README as a bug: when someone opens an issue asking how to install, fix the page and then answer the issue. Over time, the questions that people ask become your troubleshooting section.

Common README mistakes

  • Starting with history or philosophy. Readers want to know what it does first. Put the story in an "About" section further down.
  • Screenshots of terminal output. They can't be copied or searched. Use text in a code block.
  • Examples that don't run. Snippets with ... in the important spot frustrate people. Give a complete minimal example.
  • Badge walls. Three useful badges help, and twelve bury the description.
  • Absolute links to your own repository. GitHub's docs recommend relative links, which still work in forks and clones.

What I haven't verified

  • How the template renders on GitLab, Bitbucket or package registries. I only read GitHub's documentation.
  • The linter on very large READMEs, HTML-heavy ones or unusual Markdown such as nested fences.
  • That this section order suits every project. A library, a command-line tool and a web app may each want small changes.

If you'd like help tidying up documentation for a project or a team, I take on that kind of work.

Build with me

Need documentation that people use?

I write and review READMEs, API docs and onboarding guides for developer tools, and set up checks that keep them from going stale.

See services Get in touch

What I ran this against

  • Python 3.13.5 on Linux, standard library only, run on 17 November 2026. 5 tests pass.
  • The linter was run on the template (it reports only the two files the template links to, CONTRIBUTING.md and LICENSE, which don't exist in the demo folder) and on a deliberately bad README (7 findings, exit status 1). The tests also cover code blocks being ignored when looking for headings and links, and GitHub's rule that a link beginning with / is relative to the repository root.
  • The linter checks structure, not quality. It cannot tell you whether your instructions work: only running them on a clean machine can.
  • I did not test how the template renders on any platform other than reading GitHub's documentation about it.

Sources checked

  • GitHub Docs, "About the repository README file" (what READMEs typically cover; README surfaced from .github, the root or docs, in that order; content beyond 500 KiB truncated; auto-generated table of contents; relative links, with links starting with / relative to the repository root; link text must be on a single line; longer documentation suits wikis): docs.github.com, read 17 November 2026.