Standard Readme
Generate and audit README.md files that comply with the Standard Readme specification.
Two Modes
Write mode (default): Generate a new README or rewrite an existing one. Audit mode: When the user asks to "check", "audit", "review", or "lint" a README, analyze it against the spec and report issues without rewriting.
The Specification
A compliant README has sections in this exact order. Some are required, some optional. Optional sections should be included only when they add real value for the project - don't pad the README with empty sections.
Section Order
1. Title REQUIRED (H1)
2. Banner optional (image, no heading)
3. Badges optional (no heading)
4. Short Description REQUIRED (plain text, no heading)
5. Long Description optional (no heading)
6. Table of Contents REQUIRED* (H2)
7. Security optional (H2)
8. Background optional (H2)
9. Install REQUIRED** (H2)
10. Usage REQUIRED** (H2)
11. [Extra Sections] optional (H2, custom titles)
12. API optional (H2)
13. Maintainer(s) optional (H2)
14. Thanks / Credits optional (H2)
15. Contributing REQUIRED (H2)
16. License REQUIRED (H2, always last)
* Table of Contents is only required when the README exceeds 100 lines (excluding the ToC itself).
** Install and Usage are optional for documentation-only repositories (no functional code).
Section Rules
Title (required)
H1 heading. Must match the repository/package name. If using a different display title, include the repo name in italics and parentheses:
# My Awesome Project _(my-awesome-project)_
Banner (optional)
Image placed directly after the title, no heading. Must reference a local image in the repository, not an external URL.
Include only if the project actually has a banner image.
Badges (optional)
One badge per line, directly after banner (or title if no banner). No heading.
[](https://github.com/RichardLitt/standard-readme)
[](https://npmjs.org/package/my-package)
Include when the project uses CI, has a published package, or benefits from status indicators. Always include the Standard Readme compliance badge.
Short Description (required)
A single line of plain text, under 120 characters. No heading, no blockquote (>). Must match the description in the package manager and GitHub repo settings.
A CLI tool that converts Markdown files to PDF with custom styling.
Long Description (optional)
One or more paragraphs after the short description. No heading. Use this to explain motivation, goals, or context that doesn't fit in 120 characters. If the title doesn't match the repo/package name, explain why here.
Table of Contents (required if >100 lines)
H2 heading. Links to every subsequent section. Does not include the title or the ToC itself. At minimum, list all H2 headings; optionally include H3/H4.
## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [Contributing](#contributing)
- [License](#license)
Security (optional)
H2 heading. Include only if the project has security considerations important enough to highlight before install/usage (cryptographic software, auth libraries, tools handling secrets). Otherwise, put security notes in an Extra Section or omit.
Background (optional)
H2 heading. Motivation, history, intellectual context. A ### See Also subsection fits here.
Install (required)
H2 heading. Must contain a code block showing how to install.
## Install
```sh
npm install my-package
Add a `### Dependencies` subsection if there are unusual or manual dependencies. Consider an `### Updating` subsection for projects where upgrades need special steps.
#### Usage (required)
H2 heading. Must contain a code block showing common usage.
- CLI tool: show the command and typical flags
- Library: show import + basic usage
- Both: include a `### CLI` subsection
```markdown
## Usage
```js
import { convert } from 'my-package'
const pdf = await convert('README.md', { style: 'github' })
#### Extra Sections (optional)
Zero or more custom H2 sections between Usage and API. Use descriptive titles relevant to the project (e.g., "Architecture", "Configuration", "Deployment"). This is the right place for project-specific content that doesn't fit the standard sections.
#### API (optional)
H2 heading. Document exported functions, classes, types. Include signatures, return types, and notable caveats. For large APIs, point to a separate `API.md`.
Include when the project exports a programmatic API that users call directly.
#### Maintainer(s) (optional)
H2 heading (`## Maintainer` or `## Maintainers`). List project maintainers with at least one contact method (GitHub profile link or email). Keep this small - people who are responsible, not everyone with commit access.
#### Thanks (optional)
H2 heading (`## Thanks`, `## Credits`, or `## Acknowledgements`). Recognize significant contributions, inspirations, or dependencies.
#### Contributing (required)
H2 heading. Must state:
1. Where to ask questions (issues, discussions, Discord, etc.)
2. Whether PRs are accepted
3. Any requirements (e.g., signing commits, running tests first)
```markdown
## Contributing
Feel free to open an issue or submit a PR. Bug reports and feature requests are welcome.
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
Link to a CONTRIBUTING.md if one exists. Link to the Code of Conduct if one exists.
License (required, always last)
H2 heading. Must be the final section. State the license name (or SPDX identifier), the copyright holder, and link to the LICENSE file.
## License
[MIT](LICENSE) (c) 2024 Jane Smith
Use UNLICENSED if no license. Use SEE LICENSE IN <filename> for complex/multi-license situations.
Write Mode Workflow
When creating or rewriting a README:
-
Gather context - Read the project's existing files to understand what it is: package.json/Cargo.toml/pyproject.toml (name, description, dependencies), existing README, LICENSE, CONTRIBUTING.md, source code structure, CI config. Don't ask the user for information you can derive from the codebase.
-
Determine relevant sections - Start with the required sections. Add optional sections only when the project justifies them:
- Banner: only if an image already exists in the repo
- Badges: if CI, package registry, or other status indicators are set up
- Long Description: if the short description can't convey the purpose alone
- Table of Contents: if the final README will exceed 100 lines
- Security: only for security-sensitive projects
- Background: if the project has non-obvious motivation or history
- API: if the project exports functions/classes for programmatic use
- Maintainers: if the project has identified maintainers
- Thanks: if there are notable acknowledgements
- Extra Sections: for project-specific content (config, architecture, deployment) that genuinely helps users
-
Write the README - Follow the section order exactly. Make sure:
- Short description is under 120 characters
- Install and Usage both have code blocks
- Code examples actually work (match the project's real API/CLI)
- No broken internal links
- License matches the actual LICENSE file
- ToC links match all H2 sections (if ToC is included)
-
Self-check - B