In the following a README is defined in its structure.
It consists of blocks, which is a (sub)section, often started by a heading.
A block can be nested into another block, and has one or more rules validating its integrity.
The position of a child block is defined by its parent.
- requires a title
- (optional) Block:
Badges - followed by description
- Even if it's just
npm install <my-package>, because sometimes it's not - Sytem dependencies (like
ffmpeg) are mentioned here
- A minimal example
- Should use / show most default values
- Shows how the developers intend the usage
- If CLI, use the most common flags in your call
- Is strictly mandatory (until further reviewed by lawyer/responsible persons - Discussion)
- (optional) link to
LICENSEfile (required, ifLICENSEfile is available in repo)
- http://shields.io/
- No constraints regarding flat, rounded, etc..
- Can also include images / gifs showing the projects' behavior
- Structure of
--helpoutput - Can be more verbose
- See default text in
standard-readmes readme - (optional) Link to
CONTRIBUTING.md - Should be the very last block before
License
- Everything not defined in this standard will just be linted to ensure proper markdown formatting (thanks to awesome
remark-lint) - Should come after required blocks, but before
Licenseblock