@appnest/readme

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 your package.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

➤ Installation

npm install @appnest/readme -D

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

➤ Getting Started (quick)

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 current README.md file to blueprint.md.
2. Run npx @appnest/readme generate

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

➤ Getting Started (slower)

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.

Blueprint

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

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

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

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

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

When running node_modules/.bin/readme generate the file README.md will be generated with the following contents:

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

Usage

Run the node_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 write node_modules/.bin/readme generate -h in your terminal if that's your cup of tea.

Configuration

To configure this library you'll need to create a blueprint.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 your blueprint.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!

➤ 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.

Title

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

@appnest/readme

The important thing to note here is that the template automatically reads your package.json file and inserts the name 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.

Logo

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 the logo field to your blueprint.json. The logo field requires an src field. Optionally you can provide values for width, height and alt. 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"
  }
}

Badges

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 the ids property in your blueprint.json and add the npm and github ids (both are optional). If you want to add your own badges you can use the badges 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, check this website out.

Description

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 your package.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 field description to your package.json file. Optionally you can also add the fields text and demo in your blueprint.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."
}

Table of Contents

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

➤ Table of Contents

• ➤ 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.

Contributors

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

➤ Contributors

Andreas Mehlsen	You?
🔥

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

{
  "contributors": [
    {
      "name": "Andreas Mehlsen",
      "email": "[email protected]",
      "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 the info array. That one is really exciting! Here you can add lines describing the contributors - for example the role of accomplishments. Take a look here for more inspiration of what you could put into the info array.

License

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

➤ License

Licensed under MIT.

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

{
  "license": "license"
}

➤ Load markdown files

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 called my-section.md. To stamp it you'll need to add {{ load:my-section.md }}.

➤ Automatic documentation

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

/**
 * Button used for clicking!
 * @slot - Default content
 */
export class MyButton extends HTMLElement {

  /**
   * Attributes being observed.
   * @returns {string[]}
   */
  static get observedAttributes() {
    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.

➤ my-button

Button used for clicking!

Properties

Slots

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

➤ A bit about this readme

By now you are probably curious to know how this README file was generated? It was created from the following blueprint.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.

➤ Custom templates

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 the templates array to your blueprint.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 or words you keep spelling wrong.

➤ Advanced!

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

Check broken links

Add the checkLinks field to your blueprint.json and you'll be notified about all broken links in your README file. This check use check-links to check links for aliveness.

{
  "checkLinks": true
}

New template syntax

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 the placeholder array to your blueprint.json file with the new syntax being ["{[", "}]"] like this.

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

Variables

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

Objects

Objects are formatted as a list with the keys being bold. If you for example want to stamp the dependencies field from your package.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

1D Arrays

If you have a 1D array it will be formatted as a list. If you for example want to stamp the the keywords field from your package.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

2D Arrays

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 your blueprint.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!

Different colored lines

If you want to change the color of the lines above headers you can change the line field in the blueprint.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 your README.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 the line 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 the line field the string "none".

Different formatted headings

If you want to change the prefix in front of the heading you can change the headingPrefix in the blueprint.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 out this website.

➤ Featured README's

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 from terkelg'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.

➤ Future work

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!

➤ FAQ

Can I see how my README file is going to look before I commit it?

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

How can I get involved?

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

I already have a large README file - I don't have time to rewrite everything!

No problem at all! Your first step can be to rename your README.md to blueprint.md and run node_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.

How can I support you?

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 ❤️

➤ Contributors

Andreas Mehlsen	You?
🔥

➤ License

Licensed under MIT.