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 `` (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