intro

gt-builder is a build tool for guidedtrack that:

• offers liquid templating support
• creates inline documentation from yaml files
• generates code to clean up non-output variables
• optionally removes gtlint directives from generated files

check out the demo!

installation

npm install --save-dev @jrc03c/gt-builder

usage

command line

Usage: npx gt-build [options] [paths...]

Options:
  -d, --dist-dir <dir>
  -w, --watch
  -h, --help            display help for command

examples:

# 1. build anything in "./src" and output to "./dist":
npx gt-build

# 2. watch "path/to/src" for changes and output to "path/to/dist":
npx gt-build -w -d path/to/dist path/to/src

# 3. build specific programs and output to "./dist":
npx gt-build path/to/program1 path/to/program2 path/to/program3

note: "watching" functionality is only available at the command line.

programmatic

import { GTBuilder } from "@jrc03c/gt-build"

const builder = new GTBuilder({
  srcDir: "path/to/src",
  distDir: "path/to/dist",
})

const files = builder.build()
console.log(files)

// or manually render arbitrary source code with arbitrary data:
const template = `Hello, {{ name }}!`
const data = { name: "Alice" }
console.log(builder.render(template, data))
// "Hello, Alice!"

how it works

to create a new program, place two files together in a directory:

1. a data.yml file, and...
2. a template.gt file.

at build time, the builder searches the source directory (srcDir) recursively for data.yml files, uses them as data sources to compile their adjacent template.gt files, and writes the resulting files out to the output directory (distDir).

see the template or the demo for examples.

variables from data.yml can be accessed in template.gt using standard liquid notation: {{ someVar }}. the convention is to define variables in the yaml file in kebab-case (e.g., some-var: <value>) and then to reference the variables in template.gt in camel-case (e.g., {{ someVar }}). gt-builder performs this conversion automatically.

variables are just the tip of the iceberg, though. the full power of liquid is available to you! thus you can use loops, conditionals, filters, and any other features offered by liquidjs.

on the other hand, you don't have to use liquid templating at all if you don't want to! it's completely optional. if you don't use liquid syntax in a particular template.gt, then the generated output file will be identical to the template.gt file.

special variables

two special variables are created dynamically at build time and made available for use in template.gt:

1. docs = an inline documentation string
2. cleanup = a string of variable assignments that can be used to "clean up" variables at the end of the program

it's common to place {{ docs }} at the very top of your template.gt file and {{ cleanup }} at the very bottom, though that's merely a convention, not a requirement. they're just standard variables that can be referenced via liquid syntax, and template.gt files are not required to reference them.

roadmap

features i'd like to add include:

• automatic linting via gtlint
• docs customization
• liquid customization
• output file name customization