Skip to content

Latest commit

 

History

History
124 lines (95 loc) · 6.44 KB

example-project-3-templates-partials-helpers-preprocessor.md

File metadata and controls

124 lines (95 loc) · 6.44 KB
Raw

Templates, Partials, Helpers and the Preprocessor

All templates and partials can be overridden by customized versions (it is currently not possible to remove a template completely). You can find the default configuration in the handlebars/ directory.

Partials and Templates

The following partials exist by default:


├── api.md.hbs
├─┬ badge/
│ ├── appveyor.md.hbs
│ ├── codecov.md.hbs
│ ├── coveralls.md.hbs
│ ├── gh-workflows.md.hbs
│ ├── greenkeeper.md.hbs
│ ├── npm.md.hbs
│ └── travis.md.hbs
├── badges.md.hbs
├── changelog.md.hbs
├── howitworks.md.hbs
├── installation.md.hbs
├── license.md.hbs
├── overview.md.hbs
└── usage.md.hbs

The partials can be used by calling for example by adding {{> api.md}} (without the .hbs extension) to a template or another partial.

You can create a directory .thought/partials in the your project root, that has the same structure. If you create a file .thought/partials/contributing.md.hbs, it will replace the default contributing.md.hbs partial.

The same applies for templates. The default set of templates is


└── README.md.hbs

For every file in the templates/ directory, a file is created in your project root (removing the .hbs extension).

Generate replacement files via CLI

You can use the command

thought eject partial contributing.md.hbs

to automatically create the file .thought/partials/contributing.md.hbs with the default contents. If you are not sure which partials and templates you can specify in the command-line, run

thought eject

without any further parameters. It will display a list of files that exist by default and are not yet overridden in your project.

Handlebars-Helpers

Thought comes with a default set of Handlebars-helpers that can be called from within templates and partials. Have a look at the API docs of the builtin-helpers. All helpers that are built into Handlebars are also available.

If you want to provide your own helpers (for example to perform some project-specific computations) you can create a file named .thought/helpers.js or .thought/helpers.cjs in your project. This file should export an object of helper-functions like

module.exports = {
  myHelper: function(value) { ... },
  myHelper2: function(value) { ... },
}

Those helpers are registered with the handlebars engine in addition to the default helpers. If the name equals a default helper, that helper will be replaced by your helper. Currently there is no way to call the old helper from within the new helper.

Thought uses the promised-handlebars-package to allow helpers that return promises. So, in your helpers, you will never receive a promise as parameter or as context data, but if you return promises, they will be resolved seamlessly.

Customizing the preprocessor

Thought uses preprocessor.js function to extend the package.json before passing it to the handlebars engine. You can create a file named .thought/preprocessor.js in your project to supply your own preprocessor. If you do that, you should run the old preprocessor by calling this.parent(data) from within your custom function. Some partials and template rely on the data created there.

Beware that the default preprocessor returns a promise.

Here is an example-project that uses all the possibilities described above:


├─┬ .thought/
│ ├── helpers.js
│ ├─┬ partials/
│ │ └── overview.md.hbs
│ ├── preprocessor.js
│ └─┬ templates/
│   ├── CONTRIBUTING.md.hbs
│   └── NEW_FILE.md.hbs
├── CONTRIBUTING.md
├── NEW_FILE.md
├── README.md
├── index.js
└── package.json

Tutorial & Examples:

Back to the README