Skip to content
oss-kit
Install

Every fenced code block in the README says what consumes it

Rule
R-DOC-07
Area
Documentation · 7 of 10
Forge scope
GitHub and GitLab
Fixed by
oss-readme

A block of text in a box tells a reader nothing about where it goes. Two blocks in a row, one a shell command and one the contents of a configuration file, look identical and get pasted into the same place.

Observable check

every fenced code block in README.md carries a language tag, and every block whose destination is not a shell is preceded by a sentence naming the file, tool, or prompt it goes to.

Where this comes from

No upstream source. This is oss-kit's own position, and the argument for it is below.

No README specification addresses where the contents of a code block are supposed to go. Observed: two adjacent fenced blocks, one a shell command and one the body of a configuration file, render identically and get pasted into the same place. A language tag narrows the guess and does not answer it, which is why the check asks for both the tag and a sentence naming the destination. Retire this rule if renderers begin labelling blocks by destination; none does today.

Read the whole standard