README.md Editor & Generator

Philosophy

A README is the front door of your project. It should answer three questions in under 30 seconds:

1. •What does this project do?
2. •Why should I care?
3. •How do I get started?

Everything else is progressive disclosure.

Before You Start

1. •Read the existing README (if any) with the Read tool — never overwrite blindly
2. •Scan the codebase to extract real data:
   • •cat package.json → name, version, description, scripts, dependencies
   • •ls src/ → project structure
   • •git remote -v → repo URL for badges
   • •cat LICENSE → license type
   • •cat .env.example → required environment variables
3. •Identify the audience: open-source contributors, team members, end users, recruiters?

README Structure (Canonical Order)

# Project Name

Short one-liner description (matches package.json description).

![Hero image or demo GIF](link)    ← optional, high impact

## Badges (optional)
## Features
## Demo / Live Site
## Tech Stack
## Getting Started
### Prerequisites
### Installation
### Environment Variables
### Running Locally
## Usage / Examples
## Project Structure
## Scripts Reference
## API Reference (if applicable)
## Roadmap
## Contributing
## License
## Acknowledgments

Not every project needs every section. Use judgment:

• •Portfolio / personal project → Features, Tech Stack, Getting Started, License
• •Open-source library → All sections, especially API Reference and Contributing
• •Internal tool → Getting Started, Scripts, Environment Variables, Project Structure

Section-by-Section Guidelines

Title & Description

# Project Name

One-sentence description. No marketing fluff. State what it does.

• •Extract from package.json description field if available
• •Never start with "This is a..." — just state what it does
• •Max 2 lines

Badges

Generate badges from real project data. Use shields.io format:

![Build](https://img.shields.io/github/actions/workflow/status/USER/REPO/ci.yml?branch=main)
![License](https://img.shields.io/github/license/USER/REPO)
![Version](https://img.shields.io/github/package-json/v/USER/REPO)
![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)

Common badge categories:

• •Build status: CI/CD pipeline status
• •Version: package.json version or latest release
• •License: from LICENSE file
• •Tech: Node version, framework version
• •Quality: test coverage, code quality
• •Activity: last commit, open issues

Rules:

• •Only add badges for things that actually exist (don't add coverage badge if no tests)
• •Max 6 badges — more than that is noise
• •Order: build → version → license → tech → quality

Features

## Features

- **Feature name** — Short description of what it does and why it matters
- **Another feature** — Concrete benefit, not vague marketing

Rules:

• •Scan the codebase to list REAL features, not aspirational ones
• •Use bold for feature name, dash, then description
• •Each feature = 1 line (not a paragraph)
• •Group related features if > 8 items
• •If the project has i18n, mention supported languages

Tech Stack

Use a table for readability:

## Tech Stack

| Category      | Technologies                          |
|---------------|---------------------------------------|
| Framework     | Astro 5, React 19                     |
| Styling       | Tailwind CSS 3.4, CSS custom props    |
| Content       | Markdown/MDX, Zod schema validation   |
| Deployment    | GitHub Pages, GitHub Actions           |

Rules:

• •Extract real dependencies from package.json
• •Include version numbers for major frameworks
• •Group by category: Framework, Styling, State, Testing, Deployment, etc.
• •Don't list every dev dependency — focus on architectural choices

Getting Started

## Getting Started

### Prerequisites

- Node.js >= 18
- pnpm (recommended) or npm

### Installation

git clone https://github.com/USER/REPO.git
cd REPO
pnpm install

### Environment Variables

Copy `.env.example` to `.env` and fill in the values:

cp .env.example .env

| Variable          | Description              | Required |
|-------------------|--------------------------|----------|
| `DATABASE_URL`    | PostgreSQL connection    | Yes      |
| `API_KEY`         | Third-party API key      | No       |

### Running Locally

pnpm dev

Rules:

• •Extract scripts from package.json — use the ACTUAL commands
• •If .env.example exists, document every variable
• •Always specify the package manager the project uses
• •Include the port number if it's a web project

Project Structure

## Project Structure

src/
├── components/    # Reusable UI components
├── layouts/       # Page layouts
├── pages/         # Route pages (file-based routing)
├── content/       # MDX content collections
├── styles/        # Global styles and Tailwind config
├── lib/           # Utility functions and helpers
└── assets/        # Static assets (images, fonts)

Rules:

• •Generate from actual ls / find output — never invent structure
• •Only show 2 levels deep max
• •Add brief comment for each directory
• •Skip node_modules, .git, dist, build

Scripts Reference

## Scripts

| Command           | Description                    |
|-------------------|--------------------------------|
| `pnpm dev`        | Start dev server on :4321      |
| `pnpm build`      | Production build to `./dist`   |
| `pnpm preview`    | Preview production build       |
| `pnpm lint`       | Run ESLint                     |
| `pnpm test`       | Run test suite                 |

Rules:

• •Extract ALL scripts from package.json
• •Add the port number for dev/preview
• •Mention output directory for build

License

## License

This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.

• •Read the actual LICENSE file to determine the type
• •Link to the file, don't paste the full text

Editing an Existing README

When asked to edit (not generate from scratch):

1. •Read the full current README with the Read tool
2. •Identify what's wrong or missing — compare against the canonical structure
3. •Preserve the author's voice and style — don't rewrite everything
4. •Use targeted edits with the Edit tool — don't replace the whole file
5. •Keep custom sections the author added — they're intentional

Common edit requests and how to handle them:

• •"Update the README" → Scan codebase for changes, update outdated sections
• •"Add badges" → Check CI, license, package.json for real badge data
• •"Improve the README" → Check structure order, missing sections, outdated info
• •"Make it bilingual" → See Bilingual README section below
• •"Add table of contents" → Generate from actual headings

Bilingual README

Two approaches depending on content length:

Approach A — Language switcher (recommended for shorter READMEs):

# Project Name

🇬🇧 [English](#english) | 🇫🇷 [Français](#français)

---

## English

[Full content in English]

---

## Français

[Full content in French]

Approach B — Separate files (for longer READMEs):

README.md          ← Default language (usually English)
README.fr.md       ← French version

With a link at the top of each:

🇫🇷 [Version française](README.fr.md)

Rules:

• •NEVER use machine-translation-style French — write natural, technical French
• •Keep technical terms in English when they're standard (e.g., "pull request", "commit", "deploy")
• •Badge URLs stay identical in both versions
• •Translate section headers but keep anchor links working

Table of Contents Generation

Generate TOC from actual headings in the file:

## Table of Contents

- [Features](#features)
- [Tech Stack](#tech-stack)
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
- [Project Structure](#project-structure)
- [License](#license)

Rules:

• •Only generate TOC if README has > 5 sections
• •Use GitHub-compatible anchor links (lowercase, hyphens, no special chars)
• •Indent for h3 subsections
• •Don't include h1 (title) or the TOC itself in the TOC

Quality Checklist

Before finishing any README edit, verify:

• • All links work (no placeholder URLs)
• • Code blocks have language identifiers (bash, json, etc.)
• • Commands are copy-pasteable (no $ prefix, no > prefix)
• • Version numbers match package.json
• • Screenshots/GIFs actually exist at referenced paths
• • No "Lorem ipsum" or "TODO" left in the file
• • License matches the actual LICENSE file
• • Repo URL is correct (check git remote -v)
• • .env.example variables are all documented
• • Scripts match actual package.json scripts

Anti-Patterns

• •❌ Writing a README without scanning the codebase first
• •❌ Adding badges for things that don't exist (coverage badge with no tests)
• •❌ Pasting entire LICENSE text instead of linking
• •❌ Using $ or > before shell commands (breaks copy-paste)
• •❌ Marketing language ("revolutionary", "blazing fast", "cutting-edge")
• •❌ Documenting features that aren't implemented yet without marking them
• •❌ Screenshots that don't match the current UI
• •❌ Hardcoding usernames/URLs that should be dynamic