How do I use common-readme to generate a README?

Install it globally with npm install -g common-readme, then run common-readme > README.md in your project directory. This creates a new README with metadata pulled from package.json and stub sections ready for editing.

Can I customize the sections in common-readme output?

No, common-readme generates a fixed structure based on cognitive funneling principles. Any customization requires manually editing the markdown file after generation, as the tool doesn't support configurable templates.

common-readme vs standard-readme: which is better?

common-readme focuses on Node.js with automatic metadata extraction and cognitive funneling, while standard-readme might offer more community-driven flexibility. Choose based on your need for quick standardization versus customizable formats.

Does common-readme work with TypeScript or other JavaScript frameworks?

Yes, as long as the project has a package.json file, common-readme can generate a README. However, it doesn't specifically handle framework-specific documentation like TypeScript type definitions or React component examples.

How to update an existing README with common-readme?

You need to regenerate the README manually by running common-readme > README.md again, but this may overwrite existing content. It's best used for initial creation or when starting fresh, not for incremental updates.

What are the alternatives to common-readme for README generation?

Alternatives include readme-md-generator for more customizable templates, standard-readme for a community-standard format, or manual tools like JSDoc for API documentation. common-readme stands out for its Node.js focus and cognitive funneling approach.

Open-Awesome

Common Readme

JavaScript

A command-line tool that generates standardized README files for Node.js modules by extracting metadata from package.json.

GitHub

397 stars237 forks0 contributors

What is Common Readme?

common-readme is a command-line tool that generates standardized README files for Node.js modules. It extracts metadata from package.json and creates a structured markdown document following principles of cognitive funneling, helping developers produce consistent documentation with minimal effort.

Target Audience

Node.js module authors who want to create professional, consistent READMEs quickly, and developers who frequently evaluate npm packages and benefit from standardized documentation formats.

Value Proposition

It saves time by automating README boilerplate, ensures consistency across projects, and improves module usability by adhering to a community-informed structure that helps consumers quickly understand what a module does.

Overview

:star2: « a common readme for node »

Use Cases

Best For

Generating initial README files for new Node.js modules
Standardizing documentation across multiple packages in a monorepo
Ensuring new contributors follow consistent documentation practices
Improving npm package discoverability through structured READMEs
Reducing time spent on documentation boilerplate for solo developers
Creating READMEs that prioritize user experience with cognitive funneling

Not Ideal For

Projects requiring highly customized or non-standard README structures beyond the fixed format
Non-Node.js ecosystems where package.json is not used or relevant
Teams using dynamic documentation generators that auto-update from code comments or CI/CD pipelines
Projects needing embedded interactive elements, complex diagrams, or non-markdown features in READMEs

Pros & Cons

Pros

Automatic Metadata Extraction

Pulls module name, description, and license directly from package.json, minimizing manual configuration as stated in the README under 'No surprises'.

Cognitive Funneling Design

Organizes content from general overview to specific details, helping readers quickly assess relevance, inspired by Perl's CPAN and explained in the 'Common format' section.

Vanilla Markdown Output

Generates plain markdown files without proprietary formats or lock-in, ensuring compatibility with any tooling, as highlighted in the 'No lock in' principle.

Boilerplate Reduction

Provides pre-populated section stubs for Usage, API, and Examples, allowing authors to focus on content rather than structure, mentioned in the 'Usage' section.

Cons

Fixed Format Limitations

The README structure is predefined and not easily customizable, which might not fit projects needing unique sections or layouts beyond the standard template.

One-time Generation

It's a CLI tool run once; it doesn't support continuous updates or integration with code changes, requiring manual regeneration for updates.

Node.js Exclusive

Designed specifically for Node.js modules reliant on package.json, making it unsuitable for projects in other languages or without this file.

Frequently Asked Questions

Related Projects

GitHub Readme Stats

:zap: Dynamically generated stats for your github readmes

Stars79,788

Forks35,553

Last commit23 days ago

readme-md-generator

📄 CLI that generates beautiful README.md files

Stars11,125

Forks1,370

Last commit3 years ago

README Typing SVG

⚡ Dynamically generated, customizable SVG that gives the appearance of typing and deleting text for use on your profile page, repositories, or website.

Stars9,103

Forks1,591

Last commit5 days ago

Standard Readme

A standard style for README files

Stars6,332

Forks2,511

Last commit1 month ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub