Guide · Open source
How to use readme-md-generator: generate a README.md in your project
Updated · written with AI from the project's own documentation and checked against our catalogue data
readme-md-generator is a command-line tool that creates a README.md file for your project. It asks you a series of questions in the terminal and fills in the answers using an ejs template. This guide shows you how to run it, use the default answers, and supply your own template.
readme-md-generatorkefranabg/readme-md-generator · ★ 11.1k · MIT Install options & downloads Quick start
- 1Check Node.js and npm. Confirm Node.js and npm are installed, with Node.js at least 9.3.0 and npm at least 5.5.0 according to the package's engines field.
- 2Open your project root. Change into the root folder of the project where the README.md should be created.
- 3Run the generator. Run npx readme-md-generator and answer the questions in the terminal.
- 4Or accept defaults. Run npx readme-md-generator -y to use default values for all questions.
- 5Use a custom template if needed. Run npx readme-md-generator -p with the path to your ejs template file.
- 6Edit the result. Review the generated README.md and add the project details the generic layout does not cover.
What you need before you run it
readme-md-generator is run through npx, so you need Node.js and npm installed. The package's engines field lists node >=9.3.0 and npm >=5.5.0. npx is shipped by default with npm 5.2.0 and later.
The tool works best in a project that already has a package.json and a git configuration, because it reads both to suggest default answers. The README says the package.json is not required to run the tool.
- Node.js (engines field: node >=9.3.0)
- npm (engines field: npm >=5.5.0; npx ships with npm 5.2.0 and later)
Generate a README interactively
Open a terminal at the root of your project and run the command below. The tool asks questions in the terminal, and you answer them to build your README.md.
The README notes that the tool reads your package.json and git configuration and uses them to suggest default answers while you go through the questions.
npx readme-md-generatorSkip the questions with default values
If you want to accept the default value for every question, add the -y flag. This runs the generator without the question flow and uses the defaults.
npx readme-md-generator -yUse your own ejs README template
The -p option lets you point the generator at your own ejs README template. Replace the path with the location of your template file.
The project's repository has a folder of ejs README template examples you can look at before writing your own.
npx readme-md-generator -p path/to/my/own/template.mdEdit the output for your project
The README does not say how much the generated file covers, so treat the output as a starting point. A generic template layout will usually need manual edits to describe your project in detail.
The README also shows an example package.json with good metadata, including name, description, author, license, homepage, repository, bugs and engines fields. Filling these in gives the generator better defaults.
- Check the description, author and license answers against your package.json.
- Add project-specific sections such as usage details the template does not cover.
What people use it for
- Create a first README for a new project that has no documentation yet.
- Reuse answers from package.json and git config so you type less during setup.
- Standardise README layout across several projects by supplying one shared ejs template with -p.
- Generate a starting README that you then refine by hand for a public release.
Frequently asked questions
Is readme-md-generator free to use?
The project is licensed under the MIT licence, as stated in its README and repository. The README does not list any price or paid tier.
Do I need to install readme-md-generator before using it?
The README shows running it directly with npx readme-md-generator at your project root, and no separate install step is shown. npx must be available, which ships with npm 5.2.0 and later.
What do I need installed to run readme-md-generator?
You need Node.js and npm. The package's engines field lists node >=9.3.0 and npm >=5.5.0.
What does the -y option do?
The -y flag uses default values for all questions instead of asking you each one in the terminal. You can run it as npx readme-md-generator -y.
Can I use my own README design?
Yes. The -p option accepts a path to your own ejs README template, for example npx readme-md-generator -p path/to/my/own/template.md. Example templates are kept in the project's templates folder.
Are there alternatives to readme-md-generator?
Comparable projects named in our analysis are readme-generator, readme.md-generator and documentation.js. Compare them on how they handle questions, templates and output before choosing one.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
readme-md-generator suits developers starting a new project who want a README quickly, especially if they already have a package.json and git config for useful defaults, or want to supply their own ejs template. It is a poor fit for projects that need a detailed, project-specific README, and the last push in the source is from 2022, so check its current maintenance before relying on it.
Install options & downloads