readme-gen

Auto-generate beautiful README files from your project structure.

Why?

Writing a good README takes time. This tool analyzes your project and generates a solid starting point automatically.

Features

Detects project type (Node.js, Python, Go, Rust)
Generates file structure tree
Extracts metadata from config files
Detects license automatically
Creates installation and usage instructions
Identifies test setup
Clean, professional output

Installation

npm install -g readme-gen

Or use without installing:

npx readme-gen

Usage

Basic Usage

Generate README for current directory:

readme-gen

Generate for a specific project:

readme-gen ./path/to/project

Template Options

Choose from 4 different template styles:

Minimal - Just the essentials:

readme-gen --template minimal

Standard (default) - Comprehensive but not overwhelming:

readme-gen --template standard

Detailed - Includes examples, API docs, and troubleshooting:

readme-gen --template detailed

Comprehensive - Everything including roadmap, changelog, and more:

readme-gen --template comprehensive

Other Options

Preview without writing to file:

readme-gen --no-write

Specify output file:

readme-gen --output DOCS.md

Badge Generation

Add badges to your README automatically:

# Add npm version and downloads badges
readme-gen --npm

# Add all common badges (npm, CI, coverage, quality, GitHub stars)
readme-gen --all-badges

# Add specific CI badge
readme-gen --ci github-actions    # or circleci, travis

# Add coverage badge
readme-gen --coverage codecov      # or coveralls

# Add code quality badge
readme-gen --quality codeclimate   # or codefactor

# Add GitHub stars badge
readme-gen --github

# Combine multiple options
readme-gen --npm --ci github-actions --coverage codecov

Supported badges:

📦 npm version and downloads
✅ CI/CD status (GitHub Actions, CircleCI, Travis CI)
📊 Code coverage (Codecov, Coveralls)
💎 Code quality (Code Climate, CodeFactor)
⭐ GitHub stars
📄 License

Example output with --all-badges:

[![npm version](https://img.shields.io/npm/v/package)](https://www.npmjs.com/package/package)
[![npm downloads](https://img.shields.io/npm/dm/package)](https://www.npmjs.com/package/package)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/owner/repo/actions)
[![codecov](https://codecov.io/gh/owner/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/owner/repo)
[![Maintainability](https://api.codeclimate.com/v1/badges/owner/repo/maintainability)](https://codeclimate.com/github/owner/repo/maintainability)
[![GitHub stars](https://img.shields.io/github/stars/owner/repo?style=social)](https://github.com/owner/repo)

Examples

Example 1: Basic README generation

$ cd my-new-project
$ readme-gen
Analyzing project...
Detected project type: node
Extracting package.json metadata...
Generating file tree...
✓ README.md created successfully!

Generated sections:

Project title and description from package.json
Installation instructions with npm/yarn
Usage examples from scripts
Project file structure
Contributing guidelines

Example 2: Preview before writing

$ readme-gen --no-write
# my-awesome-cli

Command-line tool for awesome things.

## Installation
npm install -g my-awesome-cli

## Usage
...
(full README printed to stdout)

Use case: Review generated content before committing, or pipe to another tool for processing.

Example 3: Python project detection

$ cd python-api
$ readme-gen
Analyzing project...
Detected project type: python
Found requirements.txt with 12 dependencies
Found pytest configuration
✓ README.md created successfully!

Generates Python-specific content:

pip install instructions
Virtual environment setup
requirements.txt reference
pytest usage examples

Example 4: Multi-language monorepo

$ readme-gen ./packages/frontend
Analyzing project...
Detected project type: node
Framework: React (detected in dependencies)
Build tool: Vite
✓ README.md created successfully!

$ readme-gen ./services/api
Analyzing project...
Detected project type: go
Found go.mod with module: github.com/myorg/api
✓ README.md created successfully!

Use case: Generate consistent READMEs for each package in a monorepo.

Example 5: Custom output for documentation

$ readme-gen --output docs/PROJECT_OVERVIEW.md
Analyzing project...
Detected project type: rust
Found Cargo.toml
✓ docs/PROJECT_OVERVIEW.md created successfully!

Use case: Generate documentation files for tools that expect specific filenames or locations.

Before/After

Before:

my-project/
├── src/
├── package.json
└── (no README)

After:

readme-gen
# Analyzing project...
# Detected project type: node
# README generated: README.md

Now you have a complete README with:

Project name and description
Badges
Installation instructions
Usage examples
Project structure
Contributing guidelines

Supported Project Types

Node.js - Detects package.json, extracts scripts and dependencies
Python - Detects setup.py, pyproject.toml, requirements.txt
Go - Detects go.mod
Rust - Detects Cargo.toml
Unknown - Still generates basic structure

Options

Usage: readme-gen [options] [path]

Arguments:
  path                  Path to the project directory (default: ".")

Options:
  -V, --version         output the version number
  -o, --output <file>   Output file path (default: "README.md")
  --no-write            Print to stdout instead of writing to file
  -h, --help            display help for command

Project Structure

readme-gen/
├── src/
│   ├── analyzer.ts       # Project analysis logic
│   ├── cli.ts            # CLI entry point
│   ├── detector.ts       # Project type detection
│   ├── fileTree.ts       # File tree generator
│   ├── template.ts       # README template generator
│   ├── types.ts          # TypeScript types
│   └── *.test.ts         # Test files
├── dist/                 # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Development

Setup

git clone https://github.com/muin-company/readme-gen.git
cd readme-gen
npm install

Build

npm run build

Run Tests

npm test

Watch mode:

npm run test:watch

Coverage:

npm run test:coverage

Local Testing

npm run build
node dist/cli.js

Or link globally:

npm link
readme-gen

Real-World Examples

1. Generate README for Multiple Projects

Batch generate READMEs for all projects in a workspace:

# Generate README for each subdirectory
for dir in ./projects/*/; do
  readme-gen "$dir"
  echo "✓ Generated README for $dir"
done

2. CI/CD Integration (GitHub Actions)

Auto-update README on every push:

# .github/workflows/readme.yml
name: Update README

on:
  push:
    branches: [main]

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Generate README
        run: npx readme-gen
      
      - name: Commit if changed
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add README.md
          git diff --staged --quiet || git commit -m "chore: auto-update README"
          git push

3. Preview Before Committing

Review generated content before overwriting existing README:

# Preview in terminal
readme-gen --no-write | less

# Compare with existing
readme-gen --no-write > README.new.md
diff README.md README.new.md

# Merge manually if satisfied
mv README.new.md README.md

4. Custom Output for Documentation Sites

Generate different formats for various needs:

# Main README
readme-gen

# Docs site version (without badges)
readme-gen --output docs/README.md

# Minimal version for npm
readme-gen --output NPM_README.md

5. Monorepo Package Documentation

Generate READMEs for all packages in a monorepo:

# From monorepo root
for pkg in packages/*/; do
  echo "Processing $pkg"
  readme-gen "$pkg" --output "$pkg/README.md"
done

# Or with more control
find packages -maxdepth 1 -type d -not -path packages | while read dir; do
  if [ -f "$dir/package.json" ]; then
    readme-gen "$dir"
  fi
done

6. New Project Bootstrapping

Start a new project with a professional README from day one:

# Create new project
mkdir my-awesome-tool && cd my-awesome-tool
npm init -y

# Write some code...
mkdir src
echo "export const hello = () => 'world'" > src/index.ts

# Generate README immediately
npx readme-gen

# Now you have:
# - package.json
# - src/index.ts
# - README.md (professional, auto-generated)

7. Pre-commit Hook

Ensure README stays updated using git hooks:

# .git/hooks/pre-commit
#!/bin/bash
readme-gen --no-write > /dev/null 2>&1
if [ $? -eq 0 ]; then
  readme-gen
  git add README.md
fi

Or with husky:

{
  "husky": {
    "hooks": {
      "pre-commit": "readme-gen && git add README.md"
    }
  }
}

Troubleshooting

"Error: No package.json found"

Problem: Running readme-gen in directory without package.json or equivalent.

Solution:

# Verify project type is detectable
ls -la

# For Node.js projects:
npm init -y  # Creates package.json

# For Python projects:
touch setup.py
# or
touch pyproject.toml

# For Go projects:
go mod init github.com/user/project

# For Rust projects:
cargo init

# Then run readme-gen:
readme-gen

Generated README is Too Basic

Problem: Output lacks detail or specific information.

Solution:

# Use detailed template:
readme-gen --template detailed

# Or comprehensive:
readme-gen --template comprehensive

# Add more metadata to package.json:
{
  "name": "my-app",
  "description": "A detailed description helps generate better README",
  "keywords": ["cli", "tool", "productivity"],
  "repository": "https://github.com/user/my-app",
  "author": "Your Name <email@example.com>",
  "scripts": {
    "start": "node index.js",
    "test": "jest",
    "build": "webpack"
  }
}

# Then regenerate:
readme-gen --template detailed

Project Type Not Detected Correctly

Problem: readme-gen identifies wrong project type or falls back to "unknown".

Debug:

# Check what files exist:
ls -la

# Node.js requires:
# - package.json

# Python requires:
# - setup.py OR pyproject.toml OR requirements.txt

# Go requires:
# - go.mod

# Rust requires:
# - Cargo.toml

# If none exist, create the appropriate config file

Solution:

# For Node.js:
npm init -y

# For Python:
touch setup.py
# or better:
cat > pyproject.toml <<EOF
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject"
version = "0.1.0"
EOF

# For Go:
go mod init github.com/user/project

# Then run:
readme-gen

README Overwrites Existing Content

Problem: Accidentally overwrote hand-written README.

Prevention:

# Always preview first:
readme-gen --no-write

# Or save to different file:
readme-gen --output README.new.md

# Compare:
diff README.md README.new.md

# Merge manually if satisfied

Recovery:

# If using git:
git checkout HEAD -- README.md
git restore README.md

# Or check git history:
git log --all --full-history -- README.md
git show <commit>:README.md > README.recovered.md

Generated File Tree is Too Large

Problem: File tree includes node_modules, dist, build folders.

Workaround:

# Current workaround: manually edit .gitignore-style filtering

# Feature request: Add --exclude option
# (Not yet implemented)

# Manual fix - edit generated README and remove unwanted paths:
nano README.md
# Delete lines with node_modules/, dist/, etc.

# Or use sed:
sed -i '/node_modules/d' README.md
sed -i '/dist\//d' README.md

Future feature (vote for it!):

# Planned:
readme-gen --exclude node_modules,dist,build

Template Option Not Working

Problem: --template flag not recognized or doesn't change output.

Solution:

# Check version:
readme-gen --version

# Update to latest:
npm update -g readme-gen

# Valid templates:
readme-gen --template minimal
readme-gen --template standard       # default
readme-gen --template detailed
readme-gen --template comprehensive

# If still not working, check spelling:
readme-gen --template=detailed  # Try with = instead of space

Badge URLs Are Broken

Problem: npm badges show wrong package name or 404.

Cause: package.json name field doesn't match npm package name.

Solution:

# Check package.json:
cat package.json | jq '.name'

# Should match published npm package:
npm view <package-name>

# If they don't match, update package.json:
{
  "name": "@your-scope/correct-name",
  ...
}

# Or if package isn't published yet, badges will 404 (expected)
# Remove --npm flag:
readme-gen --template detailed  # Without --npm

CI/CD Auto-Update Creates Conflicts

Problem: GitHub Actions commits README changes, causing merge conflicts.

Solution:

# Better approach - only update on main branch:
name: Update README

on:
  push:
    branches: [main]  # Only main, not PRs

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Check if README needs update
        id: check
        run: |
          readme-gen --no-write > README.new
          if diff -q README.md README.new > /dev/null; then
            echo "changed=false" >> $GITHUB_OUTPUT
          else
            echo "changed=true" >> $GITHUB_OUTPUT
          fi
      
      - name: Update README
        if: steps.check.outputs.changed == 'true'
        run: |
          mv README.new README.md
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add README.md
          git commit -m "docs: auto-update README [skip ci]"
          git push

Permission Denied When Writing README

Problem: Can't write to README.md file.

Solution:

# Check file permissions:
ls -la README.md

# If read-only:
chmod 644 README.md

# If owned by another user:
sudo chown $(whoami) README.md

# Or write to different location:
readme-gen --output /tmp/README.md

JSON Output Missing or Malformed

Problem: --json flag not producing valid JSON.

Current limitation:

# JSON output not yet implemented
readme-gen --json
# Error: Unknown option '--json'

# Workaround - parse markdown output:
readme-gen --no-write | pandoc -f markdown -t json

# Or feature request for future version

Monorepo: Wrong Package Analyzed

Problem: Running from monorepo root analyzes root package.json instead of specific package.

Solution:

# Always specify path:
readme-gen packages/frontend
readme-gen packages/backend
readme-gen services/api

# Or cd into package:
cd packages/frontend
readme-gen

# Batch generate for all packages:
for pkg in packages/*/; do
  echo "Generating README for $pkg"
  readme-gen "$pkg"
done

Generated Content is Outdated

Problem: README references old dependency versions or removed scripts.

Solution:

# Clean and reinstall dependencies:
rm -rf node_modules package-lock.json
npm install

# Update package.json scripts:
npm pkg set scripts.start="node index.js"
npm pkg set scripts.test="vitest"

# Remove obsolete fields:
npm pkg delete devDependencies.old-package

# Regenerate:
readme-gen --template detailed

Contributing

Contributions welcome! Feel free to:

Report bugs
Suggest features
Submit pull requests

License

MIT License - see LICENSE file for details.

Credits

Built by MUIN

Name		Name	Last commit message	Last commit date
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

readme-gen

Why?

Features

Installation

Usage

Basic Usage

Template Options

Other Options

Badge Generation

Examples

Example 1: Basic README generation

Example 2: Preview before writing

Example 3: Python project detection

Example 4: Multi-language monorepo

Example 5: Custom output for documentation

Before/After

Supported Project Types

Options

Project Structure

Development

Setup

Build

Run Tests

Local Testing

Real-World Examples

1. Generate README for Multiple Projects

2. CI/CD Integration (GitHub Actions)

3. Preview Before Committing

4. Custom Output for Documentation Sites

5. Monorepo Package Documentation

6. New Project Bootstrapping

7. Pre-commit Hook

Troubleshooting

"Error: No package.json found"

Generated README is Too Basic

Project Type Not Detected Correctly

README Overwrites Existing Content

Generated File Tree is Too Large

Template Option Not Working

Badge URLs Are Broken

CI/CD Auto-Update Creates Conflicts

Permission Denied When Writing README

JSON Output Missing or Malformed

Monorepo: Wrong Package Analyzed

Generated Content is Outdated

Contributing

License

Credits

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages