Skip to content

Latest commit

 

History

History
372 lines (274 loc) · 12.5 KB

helpers.md

File metadata and controls

372 lines (274 loc) · 12.5 KB
Raw

Helpers API

The following helpers are built-in for use in templates and partials

Members

helpers

Default Handlebars-helpers for Thought

Functions

glob(pattern, options) ⇒ Promise.<Array.<string>>

Resolves files via glob pattern

helpers

Default Handlebars-helpers for Thought

Kind: global variable

helpers.dirTree(baseDir, [globPattern], options) ⇒ string

Return a drawing of a directory tree (using archy)

Kind: static method of helpers
Returns: string - a display of the directory tree of the selected files and directories.
Access: public

Param Type Description
baseDir string the base directory from which the globPattern is applied
[globPattern] string a pattern describing all files and directories to include into the tree-view. (default: '**')
options object passsed in by Handlebars
options.hash object parameters passed in as key=value
options.hash.links boolean should a link be created for each file matching the glob?
options.hash.dot boolean should dot-files be displayed implicitely. This sets the 'dot' option in the 'glob'-module
options.hash.ignore string | Array.<string> Glob pattern of files to ignore. This sets the 'ignore' option in the 'glob'-module.
options.hash.label string a label for the root node of the tree

helpers.json(obj) ⇒ string

Display an object as indented JSON-String.

This is mainly for testing purposes when adapting templates

Kind: static method of helpers
Returns: string - JSON.stringify()
Access: public

Param Type Description
obj object the object

helpers.include(filename, language) ⇒ string

Include a file into a markdown code-block

Kind: static method of helpers
Access: public

Param Description
filename
language the programming language used for the code-block

helpers.includeRaw(filename)

Directly include a file without markdown fences.

Kind: static method of helpers
Access: public

Param
filename

helpers.example(filename)

Includes an example file into the template, replacing require() calls to the current module by require('module-name') (only single-quotes are replaced)

If your file is examples/example.js, you would do

var fn = require('../')

to load your module. That way, you get an executable script. The helper will when include

var fn = require('module-name')

in your docs, which is what a user of the module will do.

Kind: static method of helpers
Access: public

Param Type Description
filename string the name of the example file
options.hash object
options.hash.snippet boolean If set to true, only the lines between <snip> and </snip> will be included

helpers.exists(filename) ⇒ Promise.<boolean>

Return true if a file exists

Kind: static method of helpers
Returns: Promise.<boolean> - true, if the file or diectory exists
Access: public

Param Type Description
filename string the path to the file

helpers.exec(command, options) ⇒ string

Execute a command and include the output in a fenced code-block.

Kind: static method of helpers
Returns: string - the output of execSync, enclosed in fences.
Access: public

Param Type Description
command string the command, passed to child-process#execSync()
options object optional arguments and Handlebars internal args.
options.hash.lang string the language tag that should be attached to the fence (like js or bash). If this is set to raw, the output is included as-is, without fences.
options.hash.cwd string the current working directory of the example process

helpers.renderTree(object, options) ⇒ string

Render an object hierarchy.

The expected input is of the form

{
  prop1: 'value',
  prop2: 'value',
  ...,
  children: [
    {
       prop1: 'value',
       propt2: 'value',
       ...,
       children: ...
    }
  ]
}

The tree is transformed and rendered using archy

Kind: static method of helpers
Access: public

Param Type Description
object
options
options.fn function computes the label for a node based on the node itself

helpers.withPackageOf(filePath, options)

Set special variable for accessing information from the context of a file (possibly in a dependency)

This block helper executes the block in the current context but sets special variables:

  • @url: The github-url of the given file in the current package version is stored into
  • @rawUrl: The url to the raw file contents on https://raw.githubusercontent.com
  • @package: The package.json of the file's module is stored into
  • @relativePath: The relative path of the file within the repository

Kind: static method of helpers
Access: public

Param Type Description
filePath string file that is used to find that package.json
options object options passed in by Handlebars

helpers.npm(packageName)

Create a link to the npm-page of a package

Kind: static method of helpers
Access: public

Param Type Description
packageName string the name of the package

helpers.htmlId(value) ⇒ string

Convert a name into a valid id (like github does with header names)

This helper creates valid html-ids from header name. It attempts to follow the same rules that github uses to convert header names (h1, h2) into the hash-part of the URL referencing this header.

htmlId('abc') === 'abc'
htmlId('abc cde') === 'abc-cde' // Replace spaces by '-'
htmlId('a$b&c%d') === 'abcd'  // Remove all characters execpt alpahnumericals and minus
htmlId('mäxchen' === 'mäxchen' // Do not remove german umlauts
htmlId('ハッピークリスマス') === 'ハッピークリスマス' // Do not remove japanase word characters
htmlId('ABCDE') === 'abcde'   // Convert to lowercase

Kind: static method of helpers
Returns: string - a string value
Access: public

Param Type Description
value string the input value of the URL (e.g. the header name)

helpers.hasCoveralls() ⇒ Promise.<boolean>

Check, if coveralls.io is configured in this package

Check the .travis.yml and the appveyor.yml files for the string 'coveralls' and return true if any of them exists and contains the string. We expect coveralls to be configured then.

Kind: static method of helpers
Returns: Promise.<boolean> - true, if coveralls is configured
Access: public

helpers.hasCodecov() ⇒ Promise.<boolean>

Check, if codecov.io is configured in this package

Check the .travis.yml and the appveyor.yml files for the string 'codecov' and return true if any of them exists and contains the string. We expect coveralls to be configured then.

Kind: static method of helpers
Returns: Promise.<boolean> - true, if coveralls is configured
Access: public

helpers.hasGreenkeeper(options)

Check, if Greenkeeper is enabled for this repository

This can be configured in the .thought/config.js-file

module.exports = {
  badges: {
    greenkeeper: true
  }
}

Kind: static method of helpers
Throws:

  • Error if no badge is enabled but not github-repo url is found in package.json

Access: public

Param Type Description
options object options passed in by Handlebars

helpers.github(filePath) ⇒ string

Resolve the display-URL of a file on github.

This works for files in the current package and in dependencies, as long as the repository-url is set correctly in package.json

Kind: static method of helpers
Returns: string - the URL
Access: public

Param Type Description
filePath string the path to the file

helpers.repoWebUrl(gitUrl)

Returns the http-url for viewing a git-repository in the browser given a repo-url from the package.json Currently, only github urls are supported

Kind: static method of helpers
Access: public

Param Type Description
gitUrl string the git url from the repository.url-property of package.json

helpers.githubRepo() ⇒ string

Returns the current repository group and name (e.g. nknapp/thought for this project)

Kind: static method of helpers
Access: public

helpers.arr(...args)

Returns an array of the passed arguments (excluding the options-parameter). This helper can be used like {{dirTree 'dir' ignore=(arr 'file1' 'file2')}} to provide array-arguments to other helpers.

Kind: static method of helpers
Access: public

Param Type Description
...args * a list of arguments

glob(pattern, options) ⇒ Promise.<Array.<string>>

Resolves files via glob pattern

Kind: global function
Returns: Promise.<Array.<string>> - a list of files

Param Type Description
pattern string the glob
options object
options.hash object
options.hash.root string the path to the directory that acts are root dir for this glob-query