ReadmeHub is a beautiful, fast, fully client-side GitHub README generator. No server, no sign-up, no telemetry — everything runs in your browser and your data is saved locally so you never lose a draft.

Pick from 15 structurally distinct themes, fill out a smart guided form, and export a polished Markdown file in seconds. Supports both project READMEs and GitHub profile READMEs from one place.

• Node.js v18 or higher
• pnpm v8 or higher (npm install -g pnpm)

# 1. Clone the repo
git clone https://github.com/mkr-infinity/readme-hub.git
cd readme-hub
# 2. Install dependencies
pnpm install
# 3. Start the dev server
pnpm run dev

Open the URL shown in your terminal (usually http://localhost:5173) — that's it.

Prefer npm or yarn? Both work too — just swap pnpm for npm or yarn in any command.

Go to Templates and browse the 15 options. Each card shows a miniature preview of the README structure. Click "Use this theme" to start with that layout, or start from the Form and apply a theme later.

The smart form adapts to your README type:

• Project README — fill in your project name, tagline, description, features, installation steps, usage examples, contributing guidelines, license, and links.
• GitHub Profile README — fill in your bio, what you're working on, what you're learning, social links, and toggle GitHub stats widgets.

Click the Tech Picker section to browse and add 90+ technology logos as badges — no manual badge URL typing.

The Editor gives you:

• Left panel — raw Markdown source you can freely edit
• Right panel — live rendered preview (toggle between GitHub-style light or dark editor mode)
• Resizable divider — drag left or right to expand whichever side you need

When you're happy, click Copy to paste it into GitHub's web editor, or Download to get a README.md file.

Project README — put README.md in the root of your repo and commit:

git add README.md
git commit -m "docs: add README"
git push

Profile README — create a repo named exactly your GitHub username (e.g. mkr-infinity/mkr-infinity). GitHub automatically pins it to your profile page.

# Build with the /readme-hub/ base path (matches your repo name)
pnpm run build:gh-pages
# The output is in dist/public/
# Deploy to GitHub Pages (Actions, gh-pages branch, or /docs folder)

The public/404.html included in the project automatically handles SPA routing — no blank pages on direct URL access or refresh.

If your repo name is not readme-hub, edit the build:gh-pages script in package.json and set BASE_PATH=/your-repo-name/.

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages
on:
 push:
 branches: [main]
permissions:
 contents: read
 pages: write
 id-token: write
jobs:
 deploy:
 runs-on: ubuntu-latest
 environment:
 name: github-pages
 url: ${{ steps.deployment.outputs.page_url }}
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v3
 with: { version: 8 }
 - uses: actions/setup-node@v4
 with: { node-version: 20, cache: pnpm }
 - run: pnpm install
 - run: pnpm run build:gh-pages
 - uses: actions/upload-pages-artifact@v3
 with: { path: dist/public }
 - uses: actions/deploy-pages@v4
 id: deployment

In your repo settings, go to Settings → Pages → Build and deployment → Source: GitHub Actions. Your site will be live at https://<your-username>.github.io/readme-hub/ after the first successful run.

readme-hub/
├── public/
│ ├── favicon.svg # App icon
│ ├── 404.html # SPA routing fallback for GitHub Pages
│
├── src/
│ ├── components/
│ │ ├── layout.tsx # Nav, footer, cursor follower
│ │ ├── preview.tsx # Markdown renderer (GitHub + dark mode)
│ │ ├── tech-picker.tsx # 90+ tech logo selector
│ │ └── ui/ # shadcn/ui component library
│ ├── lib/
│ │ ├── store.ts # State management + localStorage
│ │ ├── templates.ts # 15 theme generators
│ │ └── tech-icons.ts # Tech logo registry
│ ├── pages/
│ │ ├── home.tsx # Landing page
│ │ ├── templates.tsx # Theme gallery
│ │ ├── form.tsx # Multi-step form
│ │ ├── editor.tsx # Split editor + preview
│ │ └── not-found.tsx # 404 page
│ ├── App.tsx
│ └── main.tsx
├── index.html
├── vite.config.ts
├── tailwind / tsconfig / package.json
└── netlify.toml # Netlify deploy config + SPA redirect

All contributions are welcome — whether it's a bug fix, a new theme, additional tech logos, or a UI improvement.

1. Fork the repo and create a branch from main:

   git checkout -b feat/my-new-theme

2. Install dependencies:

   pnpm install

3. Make your changes and test locally:

   pnpm --filter @workspace/readme-hub run dev

4. Open a Pull Request — describe what you changed and why.

• New themes — the bar is "structurally different", not just a color swap. Each template in lib/templates.ts exports a generate(data: FormData): string function.
• More tech logos — add entries to lib/tech-icons.ts with slug, name, color, and category.
• Accessibility improvements — keyboard navigation, ARIA labels, contrast ratios.
• Translations — the UI strings are not yet extracted for i18n, but PRs that add that structure are welcome.
• Bug reports — open an issue with steps to reproduce.

• Keep PRs focused — one feature or fix per PR.
• Open an issue first for anything bigger than a typo so we can discuss direction.
• Code style: TypeScript, no any unless justified, Tailwind classes preferred over inline styles.

MIT — do whatever you like, just be nice. Attribution back to this repo is appreciated but not required.