# Fiberplane Templates
> Programmatically generate Fiberplane Notebooks for repeatable workflows
## Overview
Fiberplane Templates are built with the [Jsonnet](https://jsonnet.org/) data
templating language.
This crate includes:
- Fiberplane [Jsonnet library](./fiberplane.libsonnet) with functions for
creating notebooks
([API Docs](https://docs.fiberplane.com/reference/templates-api))
- Rust library for expanding templates into notebooks and for converting
existing notebooks into templates
## Quickstart
The [Fiberplane CLI](https://github.com/fiberplane/fp) is the recommended way to
interact with Templates (see the
[docs](https://docs.fiberplane.com/docs/working-with-templates) or run
`fp help templates`).
## Structure of a Template
Most Fiberplane Templates export a Jsonnet function that accepts some parameters
and creates a notebook using the helper functions provided by the Fiberplane
Jsonnet library.
```jsonnet
local fp = import 'fiberplane.libsonnet';
local c = fp.cell;
local fmt = fp.format;
// Parameters are named and can have default values
function(incidentName='API Outage')
fp.notebook
.new('Incident Response for: ' + incidentName)
.setTimeRangeRelative(minutes=60)
.addCells([
// The library exposes helper functions for creating every cell type
c.h1('Heading'),
c.text(
// There are also helper functions for formatting text
fmt.bold('Hello World!')
)
])
```
See the [templates repo](https://github.com/fiberplane/templates) for more
detailed, use-case-specific templates.
## Snippets
Snippets are smaller pieces of Jsonnet code that produce reusable arrays of
notebook cells, rather than whole notebooks.
```jsonnet
local fp = import 'fiberplane.libsonnet';
local c = fp.cell;
local fmt = fp.format;
fp.snippet([
c.h2('I am a snippet'),
c.code('Here is some code'),
])
```
## Example Templates
There are [example templates](https://github.com/fiberplane/templates) for
various use cases such as incident response, root cause analysis, etc.
## Template API Documentation
See the [generated API docs](https://docs.fiberplane.com/reference/templates-api).
## Development
### VS Code
If you want to edit Jsonnet files in VS Code, you can use the
[Jsonnet NG](https://marketplace.visualstudio.com/items?itemName=Sebbia.jsonnetng)
extension.
You should add the following to your VS Code `settings.json` file to edit
template files without it showing errors. This includes the Fiberplane Jsonnet
library and external variables normally provided by the template expansion
functions.
```json
{
"jsonnet.libPaths": ["path/to/fiberplane/templates/"]
}
```
### Running Tests
To run the tests (including the examples), run:
```shell
cargo test --lib --examples
```
### Generating Documentation
The Jsonnet library API documentation is generated from
[JSDoc](https://jsdoc.app/) comments in
[fiberplane.libsonnet](./fiberplane.libsonnet) using
[jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).
To (re)generate the documentation, you can use this Docker command:
```shell
docker run --rm -v $PWD:$PWD node:17 npx -y jsdoc-to-markdown -c $PWD/jsdoc.json $PWD/fiberplane.libsonnet > docs/template_api.md
```
Alternatively, you can use Node.js directly by using the following command:
```shell
npx -y jsdoc-to-markdown -c jsdoc.json fiberplane.libsonnet > docs/template_api.md
```