Repository files navigation

Automatically generate a beautiful best-practice README file based on the contents of your repository
_{Use this readme generator to easily generate beautiful readme's like this one! Simply extend yourpackage.json and create a readme blueprint. On Github, the README file is like the landing page of your website because it is the first thing visitors see. You want to make a good first impression.}

• Simple: Extremely simple to use - so simple that it almost feels like magic!
• Powerful: Customize almost everything - add your own templates and variables if you like
• Awesome: The tool you don't know you need before you have many different repositories that all need maintenance

npminstall @appnest/readme-D

If you don't want to install anything you can use thenpx @appnest/readme generate command instead.

This getting started guide is super quick! Follow these two steps and you will have turned your boring readme into a pretty one.

1. Rename your currentREADME.md file toblueprint.md.
2. Runnpx @appnest/readme generate

That's it! Check out your freshly generatedREADME.md file and enjoy the fruits of what you just did.

This getting started guide is a little bit longer, but will give you some superpowers. Spend a minute reading this getting started guide and you'll have the best README file in your town very soon.

First you need to create ablueprint.md file. This blueprint is going to be the blueprint for theREADME.md file we will generate later.

Let's start simple. In order to get values from yourpackage.json file injected into the README file we use the mustache syntax ({{ .. }}). Let's say yourpackage.json file looks like this:

{"name":"@appnest/readme","version":"1.2.5"}

To get thename andversion into your README file you will need to write{{ pkg.name }} and{{ pkg.version }} in yourblueprint.md file like this:

Welcome to {{ pkg.name }}. This is version {{ pkg.version }}!

When runningnode_modules/.bin/readme generate the fileREADME.md will be generated with the following contents:

Welcome to@appnest/readme. This is version 1.2.5.

Run thenode_modules/.bin/readme generate command and a README file will be generated for you. If you want to go into depth with the readme command, check out the following options or writenode_modules/.bin/readme generate -h in your terminal if that's your cup of tea.

To configure this library you'll need to create ablueprint.json file. This file is the configuration for the templates we are going to take a look at in the next section. If you want to interpolate values from the configuration file into your README file you can simply reference them without a scope. Eg. if you have the field "link" in yourblueprint.json you can write{{ link }} to reference it.

Great. Now that we have the basics covered, let's continue and see how you can use templates!

If you have come this far you are probably interested to figure out how to use README templates. This library comes with a set of pre-defined templates to make your readme awesome, but you can of course create your own. More about that later, let's not get ahead of our self just yet.

Let's start with the title template. To generate the title you write{{ template:title }} in your blueprint. When you run thereadme command the template will generate the following:

The important thing to note here is that the template automatically reads yourpackage.json file and inserts thename from the package.

{"name":"@appnest/readme"}

That's cool. Let's go through some of the other built-in templates you might want to add.

The logo template adds a logo to your readme and looks like this:

Use the placeholder{{ template:logo }} to stamp it. You will need to add thelogo field to yourblueprint.json. The logo field requires ansrc field. Optionally you can provide values forwidth,height andalt. Below is an example on how to add the data for the logo template.

{"logo": {"src":"https://raw.githubusercontent.com/andreasbm/readme/master/assets/logo-shadow.png","width":"150"  }}

The badges template adds badges to your readme and looks like this:

Use the{{ template:badges }} placeholder to stamp it. You will need to add the data about how the badges should be generated. For that you can extend theids property in yourblueprint.json and add thenpm andgithub ids (both are optional). If you want to add your own badges you can use thebadges field.

{"ids": {"github":"andreasbm/readme","npm":"@appnest/readme"  },"badges": [    {"alt":"Custom badge","url":"https://github.com/badges/shields","img":"https://img.shields.io/badge/custom-badge-f39f37.svg"    }  ]}

If you need some inspiration for badges, checkthis website out.

The description template adds a description to your readme and looks like this:

Automatically generate a beautiful best-practice README file based on the contents of your repository
_{Use this readme generator to easily generate beautiful readme's like this one! Simply extend yourpackage.json and create a readme blueprint. On Github, the README file is like the landing page of your website because it is the first thing visitors see. You want to make a good first impression.}

Use the{{ template:description }} placeholder to stamp it. To use this template you are required to add the fielddescription to yourpackage.json file. Optionally you can also add the fieldstext anddemo in yourblueprint.json file which will be presented below the description.

// package.json

{"description":"Automatically generate a beautiful best-practice README file based on the contents of your repository"}

// blueprint.json

{"text":"Use this readme generator to easily generate beautiful readme's like this one! Simply extend your <code>package.json</code> and create a readme blueprint. On Github, the README file is like the landing page of your website because it is the first thing visitors see. You want to make a good first impression."}

The table of contents template adds a table of contents and looks like this:

• ➤ Table of Contents
• ➤ Installation
• ➤ Getting Started (quick)
• ➤ Getting Started (slower)
  • Blueprint
  • Usage
  • Configuration
• ➤ Templates
  • Title
  • Logo
  • Badges
  • Description
  • Table of Contents
  • Contributors
• ➤ Contributors
  • License
• ➤ License
• ➤ Load markdown files
• ➤ Automatic documentation
• ➤ my-button
  • Properties
  • Slots
• ➤ A bit about this readme
• ➤ Custom templates
• ➤ Advanced!
  • Check broken links
  • New template syntax
  • Variables
    • Objects
    • 1D Arrays
    • 2D Arrays
  • Different colored lines
  • Different formatted headings
• ➤ Featured README's
• ➤ Future work
• ➤ FAQ
  • Can I see how my README file is going to look before I commit it?
  • How can I get involved?
  • I already have a large README file - I don't have time to rewrite everything!
  • How can I support you?
• ➤ Contributors
• ➤ License

Use the{{ template:toc }} placeholder to stamp it. It has been scientifically proven that this template will save you approximately 392.3 hours during your life-time. Seriously.

The contributors template adds the list of contributors and looks like this:

Andreas Mehlsen	You?
🔥

Use the{{ template:contributors }} placeholder to stamp it. Let's sa To use this template your are required to add thecontributors array to yourpackage.json file like this. Only thename field is required.

{"contributors": [    {"name":"Andreas Mehlsen","email":"hello@example.com","url":"https://twitter.com/andreasmehlsen","img":"https://avatars1.githubusercontent.com/u/6267397?s=460&v=4","info": ["🔥"      ]    },    {"name":"You?","img":"https://joeschmoe.io/api/v1/random","url":"https://github.com/andreasbm/readme/blob/master/CONTRIBUTING.md"    }  ]}

Take note of theinfo array. That one is really exciting! Here you can add lines describing the contributors - for example the role of accomplishments. Take a lookhere for more inspiration of what you could put into the info array.

The license template adds a license section and looks like this:

Licensed underMIT.

Use the{{ template:license }} placeholder to stamp it. To use this template you are required to add thelicense field to yourpackage.json file like this.

{"license":"license"}

What? You heard right. You can split the contents of your readme into multiple different files to make your life easier. Let's say you have a file calledmy-section.md. To stamp it you'll need to add{{ load:my-section.md }}.

Welcome to the future. Here we haveautomatic documentation of web components!. Let's say you have the following web component inside a file calledmy-button.js.

/** * Button used for clicking! *@slot - Default content */exportclassMyButtonextendsHTMLElement{/**   * Attributes being observed.   *@returns {string[]}   */staticgetobservedAttributes(){return["disabled","role"];}/**   * Disables the element.   *@attr   *@type {boolean}   */disabled=false;/**   * Role of the element.   *@attr   *@type {string}   */role="button";}customElements.define("my-button",MyButton);

Then you can get automatic documentation for the web component by simply writing{{ doc:my-button.js }} which will result in the following content.

Button used for clicking!

If you want to learn more about how the documentation is generated, check outweb-component-analyzer.

By now you are probably curious to know how this README file was generated? It was created from the followingblueprint.md file.

{{ template:logo }}{{ template:title }}{{ template:badges }}{{ template:description }}{{ bullets }}{{ template:toc }}{{ load:readme/1-installation.md }}{{ load:readme/2-getting-started.md }}{{ load:readme/3-templates.md }}{{ load:readme/4-load-markdown.md }}{{ load:readme/5-automatic-documentation.md }}{{ load:readme/6-this-readme.md }}{{ load:readme/7-custom-templates.md }}{{ load:readme/8-advanced.md }}{{ load:readme/9-featured-readmes.md }}{{ load:readme/10-future-work.md }}{{ load:readme/11-faq.md }}{{ template:contributors }}{{ template:license }}

It really couldn't be more simple that this.

You are able to create your own templates to keep things as DRY as a hot summer day. To create your own templates you'll first need to add thetemplates array to yourblueprint.json file like this.

{"templates": [    {"name":"install","template":"Run `npm install {{ ids.npm }} to install this library!"    }  ]}

Then you can stamp your custom template using the{{ template:install }} syntax ("install" here referencing the name of the custom template). The below is an example of what is stamped to the README file using the above template.

Run `npm install @appnest/readme' to install this library!

Be creative! You can for example add a template for code-snippets orwords you keep spelling wrong.

Oh! So are you ready to open Pandora's box? Let's do it.

Add thecheckLinks field to yourblueprint.json and you'll be notified about all broken links in your README file. This check usecheck-links to check links for aliveness.

{"checkLinks":true}

If you are in the mood you can change the syntax used for matching with the templates. Let's say you want your placeholders to look like this instead{[ template:title }]. Then you'll need to add theplaceholder array to yourblueprint.json file with the new syntax being["{[", "}]"] like this.

{"placeholder": ["{[","}]"]}

If you have a variable from yourblueprint.json file you want to stamp to your README file just use the{{ ... }} syntax as usual without any scopes.

Objects are formatted as a list with the keys being bold. If you for example want to stamp thedependencies field from yourpackage.json file you write{{ pkg.dependencies }} and the dependencies will be stamped in a nice formatted way like this.

• @types/glob: ^7.1.1
• check-links: ^1.1.8
• colors: ^1.4.0
• commander: ^5.0.0
• fs-extra: ^9.0.0
• glob: ^7.1.6
• path: ^0.12.7
• web-component-analyzer: 1.0.3

If you have a 1D array it will be formatted as a list. If you for example want to stamp the thekeywords field from yourpackage.json file you write{{ pkg.keywords }} and the keywords will be stamped in a nice formatted way like this:

• opensource
• project
• readme
• template
• boilerplate
• nodejs
• maintaining
• generator

If you have a 2D array it will be formatted as a table. This is very convenient for things like documentation of API's. Let's say you have the following in yourblueprint.json.

{"properties": [    ["Attribute","Type","Description"],    ["**size**","'medium', 'large'","Determines the size" ],    ["**active**","boolean","Whether the element is active or not" ]  ]}

Then you can stamp it to your readme by writing{{ properties }} and it will be formatted as a table.

You are welcome!

If you want to change the color of the lines above headers you can change theline field in theblueprint.json. Here's an example if you want a dark line instead of the colored one.

{"line":"dark"}

The following is the dark variant of the line.

Yeah! Dark mode on yourREADME.md is awesome indeed. You have other options besides dark mode. Here's all the line styles you can choose from.

• "aqua"
• "cloudy"
• "colored"
• "cut"
• "dark"
• "fire"
• "grass"
• "rainbow"
• "solar"
• "vintage"
• "water"

If you want your own line design you can give theline field an url to an image instead. It is recommended that this image is 900px in width. If you prefer no line at all you can give theline field the string "none".

If you want to change the prefix in front of the heading you can change theheadingPrefix in theblueprint.json file. Just map the heading level to the desired prefix as shown below.

{"headingPrefix": {"1":"➜","2":"⭑"  }}

If you want some inspiration for symbols you can put infront of the headings you can check outthis website.

If you use this generator for one of your projects I would love to hear about it so I can feature it. Here's a list of some repositories using this generator for their README file.

• lit-translate
• masonry-layout
• focus-trap
• web-router
• web-config
• ts-lit-plugin
• blob

As inspiration for the layout of the generated README files I initially found inspiration fromterkelg's brilliant repository called prompts - a prime example on how every README file should look! I therefore wanted to mention him here even though he doesn't use this README generator. If you want to see an example of a brilliant README file you should definitely check his repository out.

That's it for now! Lot's of exiting features a going to be added in the future. If you stumble upon an issue or have a feature request you are very welcome to open a Github issue or pull request. Have a great day!

Yes you definitely can! There are lots of tools out there for editing/previewing Github flavored markdown. I recommend usinghttps://stackedit.io/app to preview the final result since it is super lightweight and does it job well.

Create an issue or pull-request. You are also very welcome to throw me a message at@AndreasMehlsen.

No problem at all! Your first step can be to rename yourREADME.md toblueprint.md and runnode_modules/.bin/readme generate. Already then your README should now be well-formatted. Then you can slowly replace the contents when you have time. The low-hanging fruit would be to add the table of contents and license using respectively the{{ template:toc }} and{{ template:license }} templates.

There are lot's of ways to support me! I would be so happy if you gave this repository a star, tweeted about it or told your friends about this little corner of the Internet ❤️

Andreas Mehlsen	You?
🔥

Licensed underMIT.