files/prefer-readme-md
Severity: warning · Status: enforced · Applies to: ids/**
What
If an identifier directory has a README, write it in Markdown and call it README.md.
Why
GitHub renders a README under a long list of names and markup formats, so readme.md, README.MD, README.adoc and README.rst all appear on the directory page just as README.md does. Nothing is broken. This is a convention, not a fix.
The convention earns its keep in small ways. Every identifier's documentation reads and edits the same, contributors copying a neighbouring directory copy something consistent, and a reviewer skimming a pull request does not have to work out which syntax a diff is written in.
There is one case where the name does change what a reader sees. A file written as Markdown but not named with a Markdown extension — a README or README.txt opening with a # heading — is shown verbatim, so its headings and links appear as literal punctuation rather than being rendered.
What the message is telling you
The rule says different things depending on how far the file is from the convention, because the work involved differs:
| The file is | GitHub shows it as | What it takes |
|---|---|---|
readme.md, README.MD, README.markdown | Markdown | a rename |
README.adoc, README.rst, README.textile, … | that markup, rendered | a conversion |
README, README.txt containing Markdown | verbatim text | a rename |
README, README.txt containing prose | verbatim text | a conversion |
A conversion is genuinely more than a git mv. AsciiDoc writes a heading = Title, reStructuredText underlines it, Markdown prefixes it with #; links, emphasis and line breaks differ too. Renaming the file without rewriting the content leaves a page that renders as a jumble.
Names this rule does not accept
The recognised extensions are the ones GitHub itself renders: .md, .markdown, .mdown, .mkdn, .adoc, .asciidoc, .asc, .rst, .org, .textile, .rdoc, .creole, .mediawiki, .wiki and .pod, plus a bare README and README.txt.
A name outside that set — README.me, README..md, _readme.md — is not a README to GitHub at all. It will not appear on the directory page under any syntax, so it is reported by files/only-allowed-names as a file that does not belong, not by this rule.
Wrong
ids/my-project/readme.md ← renders fine, wrong name
ids/my-project/README.MD ← renders fine, wrong name
ids/my-project/README.adoc ← renders fine, wrong syntax
ids/my-project/README ← if it contains Markdown, it is shown verbatimRight
ids/my-project/README.mdHow to fix
If only the name is wrong:
git mv ids/my-project/readme.md ids/my-project/README.mdOn a case-insensitive filesystem — macOS, Windows — Git needs two steps to record a change of case:
git mv ids/my-project/readme.md ids/my-project/readme-tmp.md
git mv ids/my-project/readme-tmp.md ids/my-project/README.mdIf the content is in another markup format, rewrite it as Markdown as well as renaming the file. These READMEs are short — a heading, a sentence about the namespace, and who maintains it — so this is usually a few minutes' work by hand. pandoc will do the mechanical part if you would rather not:
pandoc -f asciidoc -t gfm ids/my-project/README.adoc \
-o ids/my-project/README.md
git rm ids/my-project/README.adocRead the result before committing it. Converters are good at headings and lists and less good at anything unusual, and a README that came out of one still has to say the same things it said before.
How to check
Run w3id-check with --rule files/prefer-readme-md to check this rule on its own; without it the tool runs every rule, as the pull request checks do.
node tools/check/bin/w3id-check.js --rule files/prefer-readme-md ids/my-projectTesting your changes covers installing the tool, and what else is worth checking by hand.