readmeasy
Creates README.md for node modules using any template engine as easy as possible.
Usage
CLI
- First, create a README template (
README.njk,README.hbs, etc.) - Next, execute
readmeasy
$ npx readmeasyAPI
Details
- creates
README.mdfrom template (README.njk,README.hbsetc.), - if template does not exists, also creates
README.njk, - if template is created and there is a
README.md, copiesREADME.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
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 PencilRelated 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.