Design beautiful GitHub READMEs, visually.
Drag-and-drop blocks, a live GitHub-accurate preview, AI auto-fill, and one-click push to your repo — without writing raw markdown.
Readmely is a visual editor for building GitHub README files. You compose a document from reusable blocks, see it rendered exactly as GitHub would render it, and export the markdown or commit it straight to your repository.
- Visual editor. Build a README from 20 block types and reorder them by dragging.
- Block management. Multi-select, group blocks into containers, and copy, paste, or duplicate them.
- GitHub-accurate preview. See the rendered result in light and dark mode as you edit.
- AI Auto-Fill. Enter any GitHub repository and generate a complete README from its data. Uses OpenAI or Gemini when an API key is set, and falls back to profile-aware templates otherwise.
- Dynamic blocks. GitHub stats, language charts, activity graphs, typing animations, tech-stack icons, and social badges, powered by reliable public providers.
- Markdown editor and import. Edit raw markdown in a Monaco editor, or import an existing README back into editable blocks.
- Markdown linting. Flags issues such as missing alt text, broken structure, and empty sections.
- README health score. A completeness grade with concrete suggestions.
- Command palette and shortcuts. A
Cmd/Ctrl+Kpalette plus keyboard shortcuts for common actions. - Export. Copy the generated markdown or download the preview as a PNG.
- Push to GitHub. Commit the README straight to a repository via GitHub OAuth.
- Templates. More than 20 starter layouts for libraries, SaaS products, AI/ML projects, CLIs, and GitHub profiles.
| Category | Blocks |
|---|---|
| Content | Header, Text / Markdown, Table, Code Snippet, Image, Video / GIF, Divider |
| Badges and links | Badges, Social Badges, Tech Stack, Support / Donate |
| GitHub dynamic | GitHub Stats, GitHub Chart, Activity Graph, Profile Views, Contributors, Sponsors |
| Profile | Typing Animation, Checklist / Roadmap, Group (container) |
# 1. Install dependencies
pnpm install
# 2. Set up environment variables
cp .env.example .env.local # then fill in your GitHub OAuth values
# 3. Start the dev server
pnpm devOpen http://localhost:3000 and go to /studio.
Only the GitHub OAuth values are required. The rest are optional.
| Variable | Required | Purpose |
|---|---|---|
AUTH_GITHUB_ID and AUTH_GITHUB_SECRET |
Yes | GitHub OAuth (sign in and push to repo) |
AUTH_SECRET |
Yes | Session encryption. Generate with openssl rand -base64 33 |
OPENAI_API_KEY or GEMINI_API_KEY |
No | AI-written auto-fill. Without it, auto-fill uses templates |
GITHUB_ACCESS_TOKEN |
No | Higher GitHub API rate limit for signed-out auto-fill |
Create a GitHub OAuth App under Settings, Developer settings, OAuth Apps with the callback URL http://localhost:3000/api/auth/callback/github. Add your production URL as a second callback when you deploy.
| Area | Libraries |
|---|---|
| Framework | Next.js 16 (App Router), React 19, TypeScript |
| Styling / UI | Tailwind CSS v4, shadcn / Base UI, lucide-react, next-themes |
| State | Zustand |
| Editor | dnd-kit (drag and drop), Monaco Editor, cmdk (command palette) |
| Markdown | react-markdown, remark-gfm, rehype-raw |
| Export / auth | html-to-image (PNG export), NextAuth v5 (GitHub OAuth), Sonner (toasts) |
Persistence is browser localStorage.
| Command | Description |
|---|---|
pnpm dev |
Start the dev server |
pnpm build |
Production build |
pnpm start |
Serve the production build |
pnpm lint |
Lint the project |
MIT.