Awesome Github Readme Generator is an open-source web tool that creates ready-to-use README.md files for GitHub profiles and repositories through a template-based form.
What is Awesome Github Readme Generator?
This open-source web application generates README.md files for GitHub profiles and repositories from user-filled forms. It runs in the browser via a Next.js front end and produces a markdown file that the user can copy or download. The project is developed by Sashen Jayathilaka and is available on GitHub with a live demo at git-readme-generator.vercel.app.
What makes it stand out?
- Dual generator modes — supports both GitHub Profile README generation and GitHub Repository README generation; the profile generator is complete, while the repository generator is listed on the roadmap.
- Template-driven workflow — users choose a template, fill in fields, and press Generate to output a complete README.md.
- Tech stack — built with Next.js, TypeScript, Tailwind CSS, and Framer Motion for animations; styling is handled entirely with Tailwind utility classes.
- Third-party integrations — incorporates popular open-source components such as github-readme-stats, github-profile-trophy, and github-readme-streak-stats to enrich generated READMEs.
- Authentication-ready — uses NextAuth and environment variables for GitHub and Google OAuth, plus a public skill API key for additional features.
- Self-hostable — can be run locally with npm install and npm run start after cloning the repository.
Who is it for?
- GitHub users who want a polished profile README without hand-writing markdown.
- Developers who need a quick repository README for a new project.
- Open-source maintainers who want to include dynamic stats cards and badges in their READMEs.
What can you do with it?
- Profile customization: create a personal README that showcases stats, trophies, and activity graphs by selecting the profile generator and filling in GitHub username details.
- Repository documentation: generate a structured README for a repository with sections and placeholders for project information.
- Rapid prototyping: spin up a local instance and try different templates before committing to a final README.
How does it work?
The generator walks through a three-step flow: click Get Started, select a README template, fill in the desired fields, and press the Generate button. The app then produces a README.md file, which the user can save or paste into their GitHub profile or repository. To run it locally, set the required environment variables, clone the repository, run npm install, and start the server.
FAQ
Is Awesome Github Readme Generator free?
Yes, it is an open-source project distributed without a license file (as stated in the README), so the source code is publicly available on GitHub.
What environment variables do I need?
To run the project locally you need GITHUB_ID, GITHUB_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, NEXT_PUBLIC_SECRET, and NEXT_PUBLIC_SKILL_API_KEY in a .env file.
Does it generate READMEs for both profiles and repositories?
The profile README generator is implemented and completed; the repository README generator is still on the roadmap and not yet fully functional.
Can I deploy it myself?
Yes, because it is a Next.js application. After setting environment variables and running npm install, you can start it locally with npm run start, and it can be deployed to any platform that supports Next.js, such as Vercel.
