A guide on how to use a tool to generate the Readme file.
Generate a Slick README for Your Next GitHub Repo Quickly
That wonderful README file you always wanted…
Have you ever wished there was someone who would make a pro-style guide for the awesome banger project you’re working on? Someone who would do it without any mean faces or a tool that would do this automatically for you by just putting the necessary information? Well, for a lazy-bee human like us, fortunately, Mr. Franck Abgrall made a tool just for this.
The readme-md-generator tool is what I’m talking about. This will make your boring or no-info Readme file into an awesome one and we’re gonna make this Markdown file right now within minutes.
What Readme? Why Readme?
If you’re a regular open-source dev, then you can skip this part and continue. For those who’re new to terms like ‘open-source’, ‘Git/GitHub’, ‘repo’ etc., here’s what a Readme file is:
A README is a text file that introduces and explains a project. It contains information that is commonly required to understand what the project is about.
-Source: Make a README
So, in other terms, it’s a file written in the Markdown format (.md) for your open-source project, that contains the overall outline of the project like what the project is, how to get started, how others can contribute to it, and all the necessary information that one should get without peeping on your code.
The next obvious question that comes is, “Why should I make this Markdown file? What’s the need?” The importance of a Readme file lies in its content. If your Readme isn’t good with the content (missing an important detail), then you should rather don’t make it or put it upfront of your repo because its this file only which your audience will see first to get answers to the question(s) they have about the project. They might want to collaborate with that project, so if you forgot to include the Readme file or made a sloppy one, then it’s a straight no-go.
What is readme-md-generator? 👀
As its Readme says (ah, the irony!):
CLI that generates beautiful README.md files.
readme-md-generatorwill suggest you default answers by reading yourpackage.jsonandgitconfiguration.
It’s a CLI tool that promises to generate beautiful Readme files with fewer efforts, thereby making the process much quicker. It will read content from your common project files like package.json, git config, etc. to suggest you default answers during the file creation process.
The package.json file is not a necessity for it to work, you can also manually write the information it asks during the process.
What will I need?
- Basic CLI skills.
- Node and NPM.
Let’s make a Readme real quick
For this article, I’ll be using my repo hosted on GitHub. It’s Forkify-JS — a Vanilla JavaScript-based application that gets you recipe results. Just for your information, this project does include the optional package.json file (you’ll see the tool getting data from this file in the GIF below). Again, you can use any project with or without that file.
Let’s make a beautiful Readme with just two simple steps.
> Step 1: Navigating and starting the tool
You will need to open up your Terminal (or equivalent command-line) and navigate to the project folder. When you’re in your folder, you can make sure you’re in the correct one (so that you don’t mess up later) by typing ls or dir to see the folder contents. Here’s a good comparison of different commands to use for both macOS and Windows.
Next, kick-off the Readme generator with the following command while in your project root:
npx readme-md-generatorIf you’re lazy here too, then you will need to add the -y flag to accept all the default answers:
npx readme-md-generator -yThere’s also a bonus option if you want to use your own ejs Readme template:
npx readme-md-generator -p path/to/your/own/template.md> Step 2: Answering the questions
Upon finishing resolving its modules, it will start asking you a few questions regarding the project. Here’s a quick GIF of what I answered while making the Readme for the Forkify-JS project:
As you can see, the first thing it asked here was “Do you want to override existing Readme file?” This is because my project had a Readme.md file generated by this tool previously. So yes, if you want to make some changes or by accident entered something wrong the first time, you can run the command again!
That HTML template styling is optional. By saying “Yes”, it will use both Markdown and HTML code to make this MD file. The next set of questions are all about your project and you. Just fill-up the necessary details, and when it says Readme generated, you’re all done. In just two simple steps, you generated a Readme file for your project. Party parrot yet?
Not yet, we got to see that generated Readme! So, here it is:
Where to next?
I would suggest you contribute to this awesome project. It’s open-sourced, so it has its issues and PR sections where you can take a look. Also, if you didn’t like the generated file and want to edit it right on your machine without opening a browser I would suggest two great software/tools for this. The first one is Caret and the second is the VS Code’s Markdown editor extensions.
Below are some of the articles/videos by which you can learn more about Readme’s and more:
Here’s the complete Gist.
