readmeasy

Creates README.md for node modules using any template engine as easy as possible.

• Usage
• Details
• CLI Options
• Details
  • Partials
    • module-headers
  • Context
    • package
    • allShields
  • Helpers & Filters
    • firstAvailable(...input[]: any)
    • prefixLines(string: string, replacer: string = ""): string
    • changeCase(string: string, to: type): string
• Related Projects
• API
• readmeasy
  • Functions
    • createReadMe
    • findOrCreateTemplateFile
    • findTemplateFile

Usage

CLI

• First, create a README template (README.njk, README.hbs, etc.)
• Next, execute readmeasy

$ npx readmeasy

API

import createReadMe, { findOrCreateTemplateFile, findTemplateFile } from "readmeasy;

async function demo() {
  await createReadMe();
}

Details

• creates README.md from template (README.njk, README.hbs etc.),
• if template does not exists, also creates README.njk,
• if template is created and there is a README.md, copies README.md's content to template.

CLI Options

--template-extension                    - File extension of the template.
--context-files <paths>                 - js, ts, JSON5 or YAML files to get data to be passed to template under a key same as file name.
--root-context-files                    - js, ts, JSON5 or YAML files to get data to be passed to template.
--partial-dirs <paths csv>              - Paths of directories which contains partial files.
--function-files <paths csv>            - Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "helperUc" helper/filter.
--root-function-files <paths csv>       - Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "uc" helper/filter.
--engine <engine name>                  - Template engine to be used. Supports engines supported by consolidate (https://www.npmjs.com/package/consolidate).
--debug                                 - Print stack trace in errors.

Details

readmeasy finds README.njk or README.hbs in your node module root and creates README.md from it. Additionally provides some utilities for the template such as partials, handlebars helpers and nunjucks filters, and useful context data acquired from package.json.

Note: Although any template engine supported by consolidate is supported, some of the provided utilities may (mostly) not available template engines other than nunjucks and handlebars.

For an example see this README's README.njk template.

Partials

Partials are sub template files which can be included in other templates.

Example:

| Engine | Syntax | | ---------- | -------------------------------------------------- | | Handlebars | {{> module-header }} | | Nunjucks | {% include "module-header.njk" %} |

module-headers

module-headers includes module name, description, table of contents and all badges/shileds defined in package.json.

Context

Context is data provided to template files.

Example:

{{ package.name }}

package

Includes data read from module's package.json.

Example:

Hello from {{ package.name }} module!

allShields

Prints all shields (badges) read from package.json. Uses badges library under the hood. readmeasy provides a few additional shields described below:

| Shield | Example | Description | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | All shileds from badges | | See its details here | | conventionalcommits | | Conventional Commits shield. | | commitizen | | Adds Commitizen-friendly badge described here |

Example:

package.json

{
  "shields": ["commitizen", "conventionalcommits"]
}

Helpers & Filters

readmeasy provides some helper functions for handlebars and custom filters for nunjucks.

firstAvailable(...input[]: any)

Returns first defined or non-empty input. This may be useful for handlebars, because it does not provide short circuit operator like nunjucks.

Example:

{{ firstAvaialbale package.label package.name }}

is equal to below in nunjucks

{{ package.label or package.name }}

prefixLines(string: string, replacer: string = ""): string

Prefixes a string to the beginning of each line in the first string

changeCase(string: string, to: type): string

Implements the library change-case.

Available types are camel, constant, dot, header, hyphen, isLower, isUpper, kebab, lower, lcFirst, no, param, pascal, path, sentence, snake, swap, title, upper, ucFirst.

See its documentation for details.

{{ "pencil" | changeCase("title") }} outputs Pencil

Related Projects

measy - Create files using any template engine as simple as possible. Just a template and a JSON/YAML file is enough.

API

readmeasy

Functions

createReadMe

▸ createReadMe(options: object): Promise‹void›

Defined in src/index.ts:19

Creates README.md from REDAME template.

Parameters:

▪Default value options: object= {}

are the options.

Name | Type | Description | ------ | ------ | ------ | contextFiles? | string | string[] | js, ts, JSON5 or YAML files to get data to be passed to template under a key same as file name. | defaultContent? | undefined | string | Default content to create README template with. | dir? | undefined | string | Directory to serach README template. | engine? | SupportedEngine | Template engine to be used. Supports engines supported by consolidate (https://www.npmjs.com/package/consolidate). Defaults to partials. | functionFiles? | string | string[] | Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "helperUc" helper/filter. | partialDirs? | string | string[] | Paths of directories which contains partial files. | rootContextFiles? | string | string[] | js, ts, JSON5 or YAML files to get data to be passed to template. | rootFunctionFiles? | string | string[] | Files to get filter/helper functions prefixed with file name. i.e "uc()" func in "path/helper.js" becomes "uc" helper/filter. | templateExtension? | undefined | string | File extension of the template. |

Returns: Promise‹void›

findOrCreateTemplateFile

▸ findOrCreateTemplateFile(__namedParameters: object): Promise‹string›

Defined in src/utils.ts:64

Finds or creates README template file and returns the file found or created path.

Parameters:

▪Default value __namedParameters: object= {} as any

Name | Type | Default | Description | ------ | ------ | ------ | ------ | defaultContent | undefined | string | - | is the default content to create README template with. | dir | undefined | string | - | is the directory to search README template for. | templateExtension | string | "njk" | - |

Returns: Promise‹string›

path of the README template.

findTemplateFile

▸ findTemplateFile(dir?: undefined | string): Promise‹string | undefined›

Defined in src/utils.ts:51

Returns README template file by searching given directory for supported template extensions. If more than one found, returns first one.

Parameters:

Name | Type | Description | ------ | ------ | ------ | dir? | undefined | string | is the directory to search README template for. |

Returns: Promise‹string | undefined›

template file path.