Creates README.md for node modules using any template engine as easy as possible.
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();
}
- 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
, copiesREADME.md
's content to template.
--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.
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 are sub template files which can be included in other templates.
Example:
Engine | Syntax |
---|---|
Handlebars | {{> module-header }} |
Nunjucks | {% include "module-header.njk" %} |
module-headers
includes module name, description, table of contents and all badges/shileds defined in package.json
.
Context is data provided to template files.
Example:
Includes data read from module's package.json
.
Example:
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"]
}
readmeasy
provides some helper functions for handlebars
and custom filters for nunjucks
.
Returns first defined or non-empty input. This may be useful for handlebars
, because it does not provide short circuit operator like nunjucks
.
Example:
is equal to below in nunjucks
{{ package.label or package.name }}
Prefixes a string to the beginning of each line in the first 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
measy - Create files using any template engine as simple as possible. Just a template and a JSON/YAML file is enough.
▸ 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(__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(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.