The guide
A README is a front door, and its links are hinges that break without a sound
Two Markdown parsers can read the same README differently, and renaming one heading can strand every link that pointed at it.
- 652 examples in the CommonMark 0.31.2 test file
- 500 KiB of a README shown before the hosting page cuts the rest
- options-1 anchor of the second heading called Options
- mid-1970s when shipping a README file became a convention
Read the full guide Fold the guide
The front page nobody reads twice
A README is the first page a stranger meets, and usually the only one. The habit of shipping one dates to the mid-1970s, and on Unix the name was written in capitals so it would stand out near the top of a listing sorted by character code.
The job has grown since then. Hosting documentation describes the file as the place to tell people why a project is useful, what they can do with it and how to use it, and a forge looks for it in a fixed order: a hidden folder named after the forge, then the root, then a docs folder. The same documentation says that when a README is viewed there, anything beyond 500 KiB is cut off. So a README is a front page with a size limit, a fixed address and an audience that will not scroll back to check whether a link still works.
There is a quieter fact underneath. Before any person reads a README, a parser reads it, and the person sees only what that parser decided the text meant. Most of the trouble with READMEs starts in that gap between what was typed and what was rendered.
Why Markdown needed a specification
Markdown was released in 2004 by John Gruber, with help from Aaron Swartz, as a syntax description and a Perl script that turned the text into HTML. The idea was text that reads well as plain text and converts cleanly. The description, though, left real questions open, and the programs that grew up around it answered those questions in different ways, sometimes on purpose and sometimes by accident.
The CommonMark specification lists some of them. How far must a sublist be indented? Does a block quote or a heading need a blank line before it? The original description does not say, and the spec points out that these are not corner cases: they decide how ordinary documents come out.
A group of people started a standardization effort in 2012, and in 2014 it took the name CommonMark. The current version, 0.31.2, is dated 2024-01-28. Its most useful part is not the prose. It is the examples: each pairs a scrap of Markdown with the exact HTML it must produce, and the file that ships with this version holds 652 of them. A parser that claims to follow the specification can be run against every one, and either it passes or it shows you precisely where it disagrees.
A specification does not end dialects. It gives them a fixed floor to build on, and a way to say exactly where they leave it.
Two dialects, one file
The GFM dialect published its own formal specification in 2017, built on CommonMark. Version 0.29-gfm calls the dialect a strict superset of CommonMark and marks its additions as extensions: tables, task list items, strikethrough, extended autolinks and a filter for certain raw HTML. Anything the base specification already covers is meant to behave the same way, and the extensions are where the two part company.
The differences are concrete. A table written with pipes is a plain paragraph to strict CommonMark, with the pipes showing as text. A bare address that starts with www becomes a link in the dialect, with http:// added in front, while strict CommonMark leaves it as words. A script element in raw HTML passes through untouched under strict rules, but the dialect replaces its opening angle bracket with an escaped one, so it shows as text. The same filter covers nine elements: title, textarea, style, xmp, iframe, noembed, noframes, script and plaintext.
The dialect’s own specification adds a warning worth keeping in mind. It notes that the hosting site does further processing and sanitization after the Markdown has become HTML. No single specification therefore describes everything a reader sees, which is the best argument for rendering a README under both rule sets and marking each place where they disagree.
How a heading becomes an address
A link inside a README usually points at a heading, and the heading has no address until a renderer gives it one. The rule the hosting documentation publishes is short: letters are lowercased, spaces become hyphens, other white space and punctuation are removed, leading and trailing white space goes, and formatting is stripped to its text. When an anchor matches an earlier one, a hyphen and a counting number are appended. RFC 3986 explains why such a rule lives in documentation rather than in a URI standard: the fragment after the number sign has a meaning that depends on the kind of document it points into.
A fragment written with letters outside ASCII may also arrive percent-encoded, so a checker has to decode it before comparing, the same parsing and encoding that browsers expose through their URL interface.
Here is a case to try in the checker. Its example README has two headings called Options. The first gets the anchor options and the second gets options-1. The same file links to #Usage, which fails, because the heading Usage produces usage and fragments are compared exactly, capitals included. It also links to #instalation, one letter short of #installation. Of its 7 in-page links, the checker reports exactly those 2 as not landing, and suggests the right target for each.
The numbering is the quiet trap. Swap two sections that share a title and their numbers swap with them, so every link that used to reach the second one now reaches the first. The documentation says plainly that editing or reordering headings changes their anchors, and that links have to be updated to match.
Not every target is a heading. In an HTML page a browser looks for an element whose id or name attribute equals the fragment, and the hosting documentation notes that such custom anchors are not numbered with the headings and are left out of the generated outline. A checker that ignored them would report working links as broken.
Even the published rule has a wrinkle. The documentation’s own worked example keeps a capital theta in its link, although the rule it states says letters are lowercased. A tool has to pick one, and following the stated rule is the only choice that can be checked.
Reference links, alt text and the hosts a README calls
Reference links keep long addresses out of the prose. CommonMark matches their labels without regard to case, after folding white space, and when a label is defined twice the first definition wins. That leaves three ways to go wrong. A label that is used but never defined renders as literal brackets. A definition that nothing uses is dead weight. A second definition with the same label is silently ignored, which is worse than an error because nothing on the page looks wrong.
Images have their own small contract. The alt attribute carries the text shown when an image cannot be, and the World Wide Web Consortium recommends that every image have one. A screen reader reads that text aloud in place of the picture, and a text-only browser prints it. In Markdown, the description between the brackets becomes the alt text, so an image written with empty brackets reaches those readers as nothing at all. A badge is an image inside a link, which means it carries two addresses and two chances to fail.
Images also decide who gets contacted. Every absolute image source names an outside server the picture has to come from, so a row of badges is a row of third parties the README depends on, and any renderer that loads images directly asks each of them when the page opens. Links work differently: they contact nobody until someone follows them, and the words a reader clicks are what the old hypertext vocabulary calls anchor text. Listing the hosts a README will call, and flagging the ones reached over plain http, is a privacy review that takes a minute.
A table of contents is, in the old sense, a list of a work’s section titles placed before the text. In a README it is a list of in-page links, and it rots the moment a heading changes. The honest way to keep one is to rebuild it from the headings between two marker comments, so a second run replaces only that block and leaves every other byte alone.
There are limits to what a check like this can do. Relative links to other files need the repository itself, so they can only be listed. Syntax highlighting, math, diagrams, footnotes and a site’s own sanitizing are outside both specifications. A checker that never loads images cannot tell whether a badge’s server still answers. Large files are parsed in a background thread, which keeps the page responsive while a long README is read.
None of the fixes are clever. Rename a heading, run the check again and let the anchors show what moved.
Sources
Every source consulted for this guide. Links checked October 30, 2026.
- CommonMark Spec, Version 0.31.2 John MacFarlane, commonmark.org
- GitHub Flavored Markdown Spec, Version 0.29-gfm GitHub
- Basic writing and formatting syntax GitHub Docs
- About the repository README file GitHub Docs
- Uniform Resource Identifier (URI): Generic Syntax (RFC 3986) IETF, RFC Editor
- README Wikipedia
- Markdown Wikipedia
- URI fragment Wikipedia
- alt attribute Wikipedia
- Hyperlink Wikipedia
- Table of contents Wikipedia
- URL - Web APIs MDN Web Docs
- Web Workers API MDN Web Docs