Quokka is a boilerplate engine. It allows you to quickly use boilerplate templates and avoid copy-pasting chunks of code and snippets when you start a new project. You can create templates for literally anything you want!
- Generating your CI/CD configuration file
- Generating skeleton applications with your own best practices
- More
- No external dependencies Quokka is written in Go and thus is compiled to a static binary. Download or build it and you're good to go.
- Local or distant templates Quokka supports both git repositories and local files.
- Sweet output and prompts Thanks to the wonderful survey library, the prompts are unified, can display an help text and support validation.
- Clean configuration files Quokka uses YAML for its configuration file formats, making them clean and easy to read.
- Powerful templating system Quokka uses Go's template system to render the boilerplate.
- Configuration override
Need a different behavior or additional variables in a specific directory?
Just add another
.quokka.ymlfile in there. You can even overwrite variables. - Conditional prompts (sub-variables) Each variable can have its own subset of variables which will only be prompted to the user if the parent variable is filled or set to true.
- Customizable templates Quokka enables fine-grained control over what needs to be done when rendering the template. Just copy the file, ignore it, add conditionals based on what the user answered, change the template delimiters…
You can grab the latest release from the release page.
$ go get -u github.com/depado/quokka
$ cd $GOPATH/src/github.com/depado/quokka
$ make
Or directly install:
$ go get -u github.com/depado/quokka
$ cd $GOPATH/src/github.com/depado/quokka
$ make install
Quokka has two ways of retrieving the templates. It supports
git or using a local directory.
Quokka (qk) is a template engine that enables to render local or distant
templates/boilerplates in a user friendly way. When given a URL/Git repository
or a path to a local Quokka template, quokka will ask for the required values
in an interactive way except if an inpute file is given to the CLI.
Usage:
qk [template] [output] <options> [flags]
qk [command]
Available Commands:
help Help about any command
new Create a new quokka template
version Show build and version
Flags:
--debug Enable or disable debug mode
--git.depth int depth of git clone in case of git provider (default 1)
-h, --help help for qk
-i, --input string specify an input values file to automate template rendering
-k, --keep do not delete the template when operation is complete
-o, --output string specify the directory where the template should be downloaded or cloned
-p, --path string specify if the template is actually stored in a sub-directory of the downloaded file
-e, --set strings specify values on the command line
-y, --yes Automatically accept
Use "qk [command] --help" for more information about a command.
When cloning a template, Quokka will create a temporary
directory and delete it once the operation completes. If you want to keep
the template (to play with it, or simply to keep a copy), make sure you pass
the -k/--keep option. This option pairs well with the -o/--output option
which defines where the template should be downloaded/cloned.
The rendering of a Quokka template can be automated if the template was designed with this in mind and if an input file is provided on the command line.
Since there is no clear way for specifying overriding values (for example a variable that applies to a single file and overrides an already existing variable in the root config), the input values will also fill the overriding variables.
The format of the input file is also yaml. The following example demonstrates how an input file could be used:
.quokka.yml
name: "Quokka Template"
description: "New Quokka Template"
version: "0.1.0"
variables:
slack:
confirm: true
prompt: "Add Slack integration?"
variables:
channel:
required: true
webhook:
required: trueinput.yml
slack: true
slack_channel: "#mychan"
slack_webhook: "complexurlIf this input file is given to Quokka, it won't prompt for these three variables, thus requiring no input from the user to render the template.
Additionally, you can provide Quokka with the -e/--set flag (multiple time if
you wish). This works the same way as the input file but has a higher priority,
meaning that if you pass both an input file and a -e flag that defines a
variable, the one passed on the command line will have a higher priority.
The --set flags work by providing it with a key=value style kind of string.
If we take the example above using the input file, we can effectively replace
the slack_channel variable by doing so:
$ qk template/ output -i input.yml --set "slack_channel=#anotherchan"
$ # Or
$ qk template/ output -i input.yml -e "slack_channel=#anotherchan"$ # Clone the repository and execute the template that is located in _example/license
$ qk [email protected]:Depado/quokka.git output --path _example/license
$ # Clone the template in a specific directory, render it in a specific directory and keep the template
$ qk [email protected]:Depado/quokka.git myamazingproject --path _example/cleanarch --keep --output "template"
$ # Reuse the downloaded template
$ qk template/ myotherproject
$ # Pass an input file to Quokka
$ qk template/ output -i in.ymlIf quokka is installed, simply run quokka new <path>. This will ask for
basic information such as the template name, description and version with some
sane defaults (version number for example is set to 0.1.0 by default).
You can also pass these values as flags on the command line.
This command will check if the output directory and a .quokka.yml file already
exist. This command is in charge of creating a new directory and creating the
initial .quokka.yml file with those basic information, helping you getting
started with Quokka template development.
Command Line Help
$ qk new --help
Create a new quokka template
Usage:
qk new [output] <options> [flags]
Flags:
-d, --description string description of the new template
-h, --help help for new
-n, --name string name of the new template
-v, --version string version of the new template
Global Flags:
--debug Enable or disable debug mode
-y, --yes Automatically accept
To configure your template, place a .quokka.yml at the root of your template.
This is called the root configuration, and should contain some information about
your template such as its name, its version and a description.
It can also contain overrides for delimiters in the templates (defaults being
the go-style {{ .var }}) and variables.
name: "Example Quokka Template"
version: "0.1.0"
description: "An example template to show how quokka works"You can add a variables section to your root configuration (or to any
.quokka.yml file, or directly inline in your template files, see below) to
define the variables you want your user to fill in. There are three types of
input you can use:
If you just specify the name of your variable, it will result in a simple input.
variables:
name:variables:
license:
values: ["MIT", "Apache License 2.0", "BSD 3", "FreeBSD", "GPL", "LGPL", "WTFPL", "None"]This will result in a selection input where the user can choose one of the provided choices.
variables:
test:
confirm: trueIf you're using the confirm keyword, it will generate a simple yes/no input.
The value you give that confirm key becomes the default value.
You can also help your users by changing the prompt, adding a help text or providing a default value:
variables:
license:
values: ["MIT", "Apache License 2.0", "BSD 3", "FreeBSD", "GPL", "LGPL", "WTFPL", "None"]
prompt: Which license do you want for your project?"
help: "License file that will be added to your project"
default: "MIT"
name:
default: amazingproject
prompt: "What's the name of your project?"
help: "Used to render the README file and various configuration files"You can mark any variable as required using the required keyword:
variables:
name:
default: amazingproject
prompt: "What's the name of your project?"
help: "Used to render the README file and various configuration files"
required: trueThis will prevent the user from rendering your template with missing variables. Note that if you specified a default value for an input, it becomes impossible to not fill in that value. So the validator becomes obsolete.
It's not uncommon to ask for additional information when the user answered yes or filled in a variable. Thus, each variable can have its own variables:
variables:
slack:
confirm: true
prompt: "Add Slack integration?"
variables:
channel:
required: true
prompt: "In which Slack channel should the result be posted?"
webhook:
required: true
help: "See https://api.slack.com/incoming-webhooks for more information"
prompt: "Provide the Slack webhook URL:"In the example above we ask the user if he wants a Slack integration. If he answers yes to that, then we'll ask him about the Slack channel and the webhook URL. Otherwise we won't bother him with these details since they won't be used in our template rendering.
The sub variables can be accessed in your templates with the form .parent_sub.
In this case, .slack_channel and .slack_webhook.
If you place a .quokka.yml file in a sub-directory of your template, this
file will apply recursively to all the elements inside that directory and its
own sub-directories, meaning that you can override some variables, add new ones,
modify the delimiters, or completely ignore an entire directory.
For example you can completely ignore a directory:
└──── change
├── override.go
└── .quokka.yml
copy: trueIn this case, the file override.go won't be rendered (but will simply be
copied to the output directory). This would apply for every sub-directory,
except if a directory contains a .quokka.yml telling otherwise, or a
file with an inline configuration. The ignore option can also be used to
completely ignore a file or a directory.
ignore: trueYou can also configure individual files by adding a front matter at the top of the file (that will obviously be removed when rendered).
Let's say I have a file that I don't want to render but simply copy to the output directory:
---
copy: true
---
# This shouldn't be rendered at all !
You can even add per-file variables, or modify the delimiters. In fact, it's
like an inline .quokka.yml that applies to a single file.
Supported instructions are as follows:
if: condition: Conditional rendering using an expr expression that must return a boolean valuecopy: true: Do not attempt to render the file and simply copy it to its destinationdelimiters: ["[[", "]]"]: Change the delimiters used for template rendering. This can be useful for files that already are templates or use extensively the{}charsrename: newname: Rename the file to this new name once renderedignore: true: Completely ignore the file (no render, no copy)
You may want some files to not be copied or rendered according to what the user
answers to your prompt. You can use the if key (in a .quokka.yml
or inline in a file), with the name of one of your variables. For example if
you have a variable defined like this in your root config:
variables:
drone:
prompt: "Do you want to add a Drone config file?"
confirm: trueYou can then add this at the top of the file:
---
if: drone
---
workspace:
base: /go
...
This file will be rendered if, and only if, the user answered yes to that
question. Note that if and copy can work together if you just want
to copy the file and not render it.
- Ignore file list in
.quokka.yml- Use case: Add a
README.mdto document the template along withREADME.md.tmplwith arenamedirective. This would avoids the front-matter in the template documentation.
- Use case: Add a