---

✨ Overview

GitHub Profile README Builder is a fully visual, drag-and-drop editor for creating beautiful GitHub profile README.md files — zero code required. Pick from a rich library of blocks, configure them with an intuitive panel, preview the result in real time, and export production-ready Markdown in one click.

Built with Next.js 16, React 19, TypeScript, Tailwind CSS v4, shadcn/ui, Zustand, and dnd-kit.

---

🗂️ Table of Contents

• ✨ Overview
• 🗂️ Table of Contents
• 🎯 Features
• 🧱 Block Library
• 🛠️ Tech Stack
• 🚀 Getting Started
  • Prerequisites
  • Installation
  • Environment Variables
  • Development
  • Production Build
• 📁 Project Structure
• 🔌 API Routes
  • Supported Themes
• 🎨 Templates
• 🤝 Contributing
  • Adding a New Block
  • Code Style
• 📄 License

---

🎯 Features

---

🧱 Block Library

Blocks are organized into eight categories:

Layout — Structure your README

Block	Description
Container	Flex wrapper supporting row/column direction, alignment, and gap
Divider	Horizontal rule or a custom animated GIF divider
Spacer	Configurable height gap (10–100 px)

Hero — Eye-catching headers

Block	Description
Capsule Header	Animated banner via capsule-render with 7 animation types
Avatar	Circular or rounded profile image with configurable size
Greeting	Large <h1> greeting with optional emoji
Typing Animation	Animated typing SVG via readme-typing-svg with multiple lines

Content — Text and code

Block	Description
Heading	H1–H3 with alignment and emoji prefix
Paragraph	Freeform text with alignment control
Collapsible	GitHub <details> block with nested children
Code Block	Syntax-highlighted fenced code with language selector

Media — Images & GIFs

Block	Description
Image	External image with size, alignment, and border-radius
GIF	Lightweight GIF embed with width control

Social — Badges & links

Block	Description
Social Badges	One-click shields.io badges for LinkedIn, Twitter, GitHub, YouTube, Instagram, Discord, Email, Portfolio
Custom Badge	Fully custom label/message/color/logo badge

Tech Stack — Skills

Block	Description
Skill Icons	Grid of tech icons via skillicons.dev — 80+ icons available

GitHub Stats — Activity widgets

Block	Description
Stats Card	Stars, commits, PRs, issues, and rank ring
Top Languages	Compact, normal, donut, donut-vertical, or pie layout
Streak Stats	Current streak, longest streak, and total contributions
Activity Graph	30-day contribution line chart
Trophies	Trophy grid with configurable columns/rows

Advanced — Extra elements

Block	Description
Visitor Counter	komarev.com page-view badge
Quote	Static custom quote or random dev quote from API
Footer Banner	Waving capsule-render footer

---

🛠️ Tech Stack

Frontend          Next.js 16 (App Router) · React 19 · TypeScript 5
Styling           Tailwind CSS v4 · tw-animate-css · shadcn/ui (radix-nova)
State             Zustand 5
Drag & Drop       dnd-kit (sortable)
Icons             Lucide React
Theming           next-themes
Notifications     Sonner
API               Next.js Route Handlers · GitHub REST & GraphQL APIs
Fonts             Outfit · JetBrains Mono

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 18
• A package manager: npm, pnpm, yarn, or bun
• (Optional) A GitHub Personal Access Token for live stats

Installation

# 1. Clone the repository
git clone https://github.com/zntb/github-profile-readme-builder.git
cd github-profile-readme-builder

# 2. Install dependencies
npm install

# 3. Copy environment variables
cp .env.example .env.local

Environment Variables

# .env.local

# Optional – enables real GitHub stats, streak, trophies, and activity graphs.
# Create one at: https://github.com/settings/tokens
# Required scopes: read:user
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Without a token the stat widgets still render but display a "GitHub Token Required" placeholder instead of live data.

Development

npm run dev

Open http://localhost:3000 in your browser.

Production Build

npm run build
npm start

---

📁 Project Structure

github-profile-readme-builder/
├── app/
│   ├── api/
│   │   ├── activity/route.ts      # Contribution activity graph SVG
│   │   ├── stats/route.ts         # GitHub stats card SVG
│   │   ├── streak/route.ts        # Streak stats SVG
│   │   ├── top-langs/route.ts     # Top languages SVG
│   │   └── trophies/route.ts      # Trophy grid SVG
│   ├── globals.css                # Tailwind v4 tokens + custom animations
│   ├── layout.tsx                 # Root layout with ThemeProvider & fonts
│   └── page.tsx                   # Entry point → <Builder />
│
├── components/
│   ├── builder/
│   │   ├── index.tsx              # Responsive layout orchestrator (desktop / tablet / mobile)
│   │   ├── header.tsx             # Top bar: branding, Templates, Clear, Export
│   │   ├── block-sidebar.tsx      # Searchable block library with categories
│   │   ├── canvas.tsx             # dnd-kit sortable drop zone
│   │   ├── canvas-block.tsx       # Individual draggable block wrapper
│   │   ├── block-preview.tsx      # Compact canvas-level block previews
│   │   ├── config-panel.tsx       # Right-side property editor (per block type)
│   │   ├── live-preview.tsx       # Full GitHub-style README render
│   │   ├── output-panel.tsx       # Markdown output + copy/download actions
│   │   └── templates-dialog.tsx   # Template picker dialog
│   ├── ui/                        # shadcn/ui components
│   └── mode-toggle.tsx            # Light/Dark/System theme switcher
│
├── lib/
│   ├── github.ts                  # GitHub REST + GraphQL helpers, rank calc, streak calc
│   ├── markdown.ts                # Block → Markdown renderer + download/copy utils
│   ├── store.ts                   # Zustand builder store (blocks, selection, DnD)
│   ├── templates.ts               # Pre-built template definitions
│   ├── types.ts                   # Block types, prop interfaces, BLOCK_CATEGORIES
│   └── utils.ts                   # cn() Tailwind merge helper
│
└── public/                        # Static assets & favicons

---

🔌 API Routes

All stat widgets are generated server-side by built-in Next.js route handlers. They proxy and render live GitHub data as SVG images, meaning the generated Markdown will work from any host that has GITHUB_TOKEN configured.

Supported Themes

Over 50 themes are supported across all widgets, including:

default · dark · radical · tokyonight · dracula · onedark · nord · github_dark · catppuccin_mocha · gruvbox · merko · react · midnight-purple · rose_pine · and many more.

---

🎨 Templates

Four built-in templates are included to help you start quickly:

Templates are defined in lib/templates.ts and can be extended freely.

---

🤝 Contributing

Contributions are welcome! Here's how to get involved:

# Fork & clone
git clone https://github.com/<your-username>/github-profile-readme-builder.git

# Create a feature branch
git checkout -b feat/my-new-block

# Make your changes, then commit
git commit -m "feat: add <block-name> block"

# Push and open a Pull Request
git push origin feat/my-new-block

Adding a New Block

1. Add the block type to the BlockType union in lib/types.ts
2. Define its defaultProps in the relevant BLOCK_CATEGORIES entry in lib/types.ts
3. Add a preview renderer case in components/builder/block-preview.tsx
4. Add a config fields case in components/builder/config-panel.tsx
5. Add a live preview case in components/builder/live-preview.tsx
6. Add a Markdown render case in lib/markdown.ts

Code Style

• All code is TypeScript — avoid any
• Use shadcn/ui components where possible
• Follow existing Tailwind class conventions (CSS variables, cn() helper)
• Run npm run lint before submitting

We use Prettier and ESLint with a pre-commit hook. The hook will block commits if there are any lint errors or formatting issues:

# Format all files
npm run format

# Check for issues
npm run format:check
npm run lint

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

---