Every developer knows the feeling - you finish a project, push it to GitHub, and then stare at the empty README.md wondering where to even start.
So I built ReadmeForge. A block-based visual editor where you drag, drop, fill in content, and download a perfect README in minutes. No markdown skills needed.
Live at thereadmeforge.vercel.app - open source, MIT licensed.
Table of Contents
- The Problem
- What It Does
- Block Types
- How Data Is Stored
- My Favourite Detail — No Backend
- Tech Stack
- Run It Locally
- Contributing
The Problem
Writing a README from scratch is the task every developer delays as long as possible. You either:
- Copy-paste a template and spend an hour reformatting markdown
- Open some tool that spits out a generic result with no real structure
- Just skip it and ship a repo with a two-line description
ReadmeForge fixes this with a proper block-based editor — the same mental model as Notion, but output is a clean GitHub-ready README.md.
What It Does
11 Purpose-Built Block Types
Title, Badges, Description, Features, Installation, Usage, Screenshots, API Docs, Contributing, License, and Custom Markdown. Every block has a dedicated editor — no raw markdown required.
Drag-and-Drop Reordering
Powered by @dnd-kit with smooth sorting animations and a drag-ghost preview. Reorder your entire README structure in seconds.
Live Preview + Code View
Real-time markdown rendering via marked with a custom renderer for images and badges. Switch to Code View for syntax-highlighted raw markdown with line numbers — powered by react-syntax-highlighter.
Screenshots Block
Upload from device, paste from clipboard (Ctrl+V), or drop in a remote URL. Images are converted to base64 and stored locally — they survive page refreshes.
One-Click Export
Copy raw markdown to clipboard or download as README.md instantly. Live stats show word count, file size (KB), and image count in real time.
Mobile Responsive
Bottom navbar on small screens with Blocks & Palette tabs. Slide-in drawers for mobile editing. Full desktop layout with a resizable drag divider between editor and preview.
Block Types
| Block | Description |
|---|---|
| Title | Project name & tagline |
| Badges | shields.io badges with live preview |
| Description | Long-form project overview |
| Features | Bulleted feature list |
| Installation | Package manager selector + commands |
| Usage | Language selector + code editor |
| Screenshots | Upload, URL, captions, reorder |
| API Docs | Function signature, description, params |
| Contributing | Intro text + numbered steps |
| License | License type, year, author |
| Custom | Free-form markdown textarea |
How Data Is Stored
| Item | Where |
|---|---|
| Your blocks |
localStorage keyed as readmeforge:{email}:blocks
|
| Active email |
localStorage under readmeforge_activeEmail
|
| Uploaded images | Converted to base64 Data URLs, saved inline with block content |
| Onboarding state |
sessionStorage — shown once per browser session |
Enter any email on the landing page — your workspace is created instantly. Switch emails to get completely isolated workspaces for different projects. No account, no password, no server.
My Favourite Detail - No Backend
Everything lives in your browser via Zustand with persist middleware. No sign-up. No tracking. No server ever sees your content.
The email-based workspace system means you can have a workspace for your open-source library, another for your portfolio site, another for a work project — all in the same browser, completely isolated, all private.
Tech Stack
| Tool | Purpose |
|---|---|
| React + Vite | Component architecture and build tooling |
| Tailwind CSS | Utility-first styling |
| Zustand | State management with persist middleware |
| @dnd-kit | Accessible drag-and-drop reordering |
| marked | Markdown parsing with custom renderers |
| react-syntax-highlighter | Prism-powered code view with line numbers |
| Lucide React | Icon set |
| Vercel | Deployment |
Run It Locally
git clone https://github.com/byllzz/readmeforge.git
cd readmeforge
npm install
npm run dev
Open http://localhost:5173. No environment variables needed — everything runs fully client-side.
Contributing
Contributions are welcome. Good first issues:
- [ ] Add new block types — follow the pattern in
blocks.jsand create a matching*Block.jsx - [ ] Improve the markdown generator in
markdown.jsfor cleaner output - [ ] More badge providers in the Badges block
- [ ] Additional license types in the License block
- [ ] ARIA labels and keyboard navigation improvements
git checkout -b feat/your-feature
# make your changes
git commit -m "feat: your short description"
git push origin feat/your-feature
Keep PRs focused — one feature or one fix per PR. If unsure whether something fits, open an issue first.
If ReadmeForge saved you from staring at a blank README.md — a ⭐ on the GitHub repo means a lot. Drop any feedback in the comments below!