DEV Community

Alex
Alex

Posted on

Generate Beautiful READMEs from Your Code Automatically

#github #ai #documentation #tutorial

Good READMEs get GitHub stars. Bad READMEs get closed tabs. But writing documentation after building a project feels like writing an essay after finishing the exam. The motivation is gone.

Here's how to generate a complete README from your code in one command.

The Script

Create scripts/generate-readme.sh:

#!/bin/bash

# Collect project context
PACKAGE=$(cat package.json 2>/dev/null || echo "No package.json")
STRUCTURE=$(find . -type f -not -path './node_modules/*' -not -path './.git/*' | head -50)
ENTRY=$(cat src/index.ts 2>/dev/null || cat index.js 2>/dev/null || echo "No entry file")
EXAMPLES=$(ls examples/ 2>/dev/null || echo "No examples directory")

# Generate README
curl -s https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d "{
    \"model\": \"claude-sonnet-4-20250514\",
    \"max_tokens\": 2048,
    \"messages\": [{
      \"role\": \"user\",
      \"content\": \"Generate a README.md for this project. Include: project title, one-line description, features, installation, quick start, API reference (if applicable), examples, and license. Use badges where appropriate.\\n\\nPackage info:\\n$PACKAGE\\n\\nFile structure:\\n$STRUCTURE\\n\\nEntry point:\\n$(echo "$ENTRY" | head -c 3000)\"
    }]
  }" | jq -r '.content[0].text' > README.md

echo "README.md generated successfully"
Enter fullscreen mode Exit fullscreen mode

What It Produces

For a typical Node.js project, you get something like:

# StructureAI MCP Server

> Extract structured JSON from unstructured text using AI,
> directly from Claude Desktop or Cursor.

![npm](https://img.shields.io/npm/v/structureai-mcp)
![license](https://img.shields.io/badge/license-MIT-blue)

## Features
- Extract data from receipts, invoices, emails, resumes
- Custom schema support for any data structure
- 10 free requests included, no API key needed
- Works with Claude Desktop, Cursor, and any MCP client

## Installation
...

## Quick Start
...
Enter fullscreen mode Exit fullscreen mode

It reads your package.json for the name, version, and dependencies. It reads your source files for the API. It produces a README that actually matches your code.

Making It Smarter

Include Your Tests as Examples

Tests are documentation. Feed them to the AI:

TESTS=$(find . -name "*.test.*" -not -path './node_modules/*' | head -5 | xargs cat 2>/dev/null | head -c 3000)
Enter fullscreen mode Exit fullscreen mode

Add $TESTS to the prompt. The AI will extract usage patterns from your tests and turn them into README examples.

Add API Documentation

If your project exposes routes or functions, include them:

# For Express/Next.js apps
ROUTES=$(grep -r "app\.\(get\|post\|put\|delete\)\|export.*function\|router\." src/ | head -30)
Enter fullscreen mode Exit fullscreen mode

The AI generates an API reference table from your route definitions.

Generate Badges Automatically

Ask the AI to include relevant badges based on your package.json:

If the project uses TypeScript, add a TypeScript badge.
If it has tests, add a test coverage badge placeholder.
If it's on npm, add an npm version badge.
Add a license badge based on the license field.
Enter fullscreen mode Exit fullscreen mode

Extracting Project Metadata

For structured project metadata, you can use StructureAI to extract key details from your codebase:

curl -X POST https://api-service-wine.vercel.app/api/extract \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "text": "package.json: {name: structureai-mcp, version: 1.0.0, scripts: {build: tsc, test: jest}, dependencies: {@modelcontextprotocol/sdk: ^1.0, zod: ^3.22}}",
    "schema": "custom",
    "custom_fields": ["project_name", "language", "framework", "key_dependencies", "has_tests", "build_tool"]
  }'
Enter fullscreen mode Exit fullscreen mode

Use the structured output to template your README sections consistently across all your projects.

CI/CD Integration

Keep your README up to date automatically. Add a GitHub Action that regenerates it when source code changes:

name: Update README
on:
  push:
    branches: [main]
    paths: ['src/**', 'package.json']

jobs:
  readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate README
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: ./scripts/generate-readme.sh
      - name: Commit if changed
        run: |
          git diff --quiet README.md || {
            git config user.name "readme-bot"
            git config user.email "bot@example.com"
            git add README.md
            git commit -m "docs: auto-update README"
            git push
          }
Enter fullscreen mode Exit fullscreen mode

Now your README always matches your code. No manual updates needed.

README Sections That Matter

Based on analyzing top GitHub repos, these sections get the most engagement:

  1. One-liner — What it does in one sentence
  2. Quick start — Copy-paste to get running in 30 seconds
  3. Visual — Screenshot, GIF, or diagram
  4. Examples — Real-world usage, not just API reference
  5. Why this exists — The problem it solves

The AI generates all of these from your code. You just review and ship.

Try It

  1. Copy the script above to scripts/generate-readme.sh
  2. chmod +x scripts/generate-readme.sh
  3. Run it from your project root
  4. Review the generated README.md
  5. Commit and push

Your project now has documentation that actually reflects what the code does. Update it by re-running the script whenever you ship a major feature.

Built by Avatrix LLC. Check out our MCP server for structured data extraction from any text.

Top comments (0)