{"id":13826972,"url":"https://github.com/Depado/quokka","last_synced_at":"2025-07-09T02:32:59.483Z","repository":{"id":64304154,"uuid":"153021315","full_name":"depado/quokka","owner":"depado","description":"Project boilerplate engine","archived":false,"fork":false,"pushed_at":"2024-11-08T03:45:48.000Z","size":5339,"stargazers_count":29,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-08T04:28:08.877Z","etag":null,"topics":["boilerplate","engine","go","golang"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/depado.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-14T21:36:58.000Z","updated_at":"2024-11-08T03:44:07.000Z","dependencies_parsed_at":"2023-02-19T04:01:10.094Z","dependency_job_id":"8e942479-5d7f-42d4-9399-53c47ec850fe","html_url":"https://github.com/depado/quokka","commit_stats":null,"previous_names":["depado/projectmpl"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depado%2Fquokka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depado%2Fquokka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depado%2Fquokka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depado%2Fquokka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/depado","download_url":"https://codeload.github.com/depado/quokka/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225481117,"owners_count":17481157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","engine","go","golang"],"created_at":"2024-08-04T09:01:47.745Z","updated_at":"2024-11-20T06:30:40.497Z","avatar_url":"https://github.com/depado.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eQuokka\u003c/h1\u003e\n\u003ch2 align=\"center\"\u003e\n  \u003cimg src=\"/assets/mascot.png\" alt=\"mascot\" height=\"200px\"\u003e\n\n  ![Go Version](https://img.shields.io/badge/Go%20Version-latest-brightgreen.svg)\n  [![Go Report Card](https://goreportcard.com/badge/github.com/depado/quokka)](https://goreportcard.com/report/github.com/depado/quokka)\n  [![Build Status](https://drone.depa.do/api/badges/Depado/quokka/status.svg)](https://drone.depa.do/Depado/quokka)\n  [![codecov](https://codecov.io/gh/Depado/quokka/branch/master/graph/badge.svg)](https://codecov.io/gh/Depado/quokka)\n  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/depado/quokka/blob/master/LICENSE)\n  [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/Depado)\n\u003c/h2\u003e\n\n\u003ch2 align=\"center\"\u003eFriendly Boilerplate Engine\u003c/h2\u003e\n\n\u003cimg align=\"center\" src=\"/assets/quokka.gif\"\u003e\n\n- [Introduction](#introduction)\n    - [Features](#features)\n- [Installation](#installation)\n    - [Download](#download)\n    - [Build from source](#build-from-source)\n- [Usage](#usage)\n    - [Keeping the template](#keeping-the-template)\n    - [Input File](#input-file)\n    - [Set](#set)\n    - [Examples](#examples)\n- [Template Creation](#template-creation)\n    - [The root `.quokka.yml` file](#the-root-quokkayml-file)\n    - [Variable declaration](#variable-declaration)\n        - [Simple Input](#simple-input)\n        - [Selection](#selection)\n        - [Boolean/Confirmation](#booleanconfirmation)\n        - [Other options and help](#other-options-and-help)\n        - [Validation](#validation)\n        - [Sub Variables](#sub-variables)\n    - [Standard `.quokka.yml` files](#standard-quokkayml-files)\n    - [Per-file configuration](#per-file-configuration)\n    - [Conditional Rendering/Copy](#conditional-renderingcopy)\n\n# Introduction\n\nQuokka is a boilerplate engine. It allows you to quickly use boilerplate\ntemplates and avoid copy-pasting chunks of code and snippets when you start a\nnew project. You can create templates for literally anything you want!\n\n## Example Usages\n\n- Generating your CI/CD configuration file\n- Generating skeleton applications with your own best practices\n- More\n\n## Features\n\n- **No external dependencies**\n  Quokka is written in Go and thus is compiled to a static binary. Download\n  or build it and you're good to go.\n- **Local or distant templates**\n  Quokka supports both git repositories and local files.\n- **Sweet output and prompts**\n  Thanks to the wonderful [survey](https://github.com/AlecAivazis/survey)\n  library, the prompts are unified, can display an help text and support\n  validation.\n- **Clean configuration files**\n  Quokka uses YAML for its configuration file formats, making them clean\n  and easy to read.\n- **Powerful templating system**\n  Quokka uses [Go's template system](https://golang.org/pkg/text/template/)\n  to render the boilerplate.\n- **Configuration override**\n  Need a different behavior or additional variables in a specific directory?\n  Just add another `.quokka.yml` file in there. You can even overwrite\n  variables.\n- **Conditional prompts (sub-variables)**\n  Each variable can have its own subset of variables which will only be\n  prompted to the user if the parent variable is filled or set to true.\n- **Customizable templates**\n  Quokka enables fine-grained control over what needs to be done when\n  rendering the template. Just copy the file, ignore it, add conditionals based\n  on what the user answered, change the template delimiters…\n\n# Installation\n\n## Download\n\nYou can grab the latest release from [the release page](https://github.com/depado/quokka/releases).\n\n## Build from source\n\n```\n$ go get -u github.com/depado/quokka\n$ cd $GOPATH/src/github.com/depado/quokka\n$ make\n```\n\nOr directly install:\n\n```\n$ go get -u github.com/depado/quokka\n$ cd $GOPATH/src/github.com/depado/quokka\n$ make install\n```\n\n# Usage\n\nQuokka has two ways of retrieving the templates. It supports\n`git` or using a local directory.\n\n```\nQuokka (qk) is a template engine that enables to render local or distant\ntemplates/boilerplates in a user friendly way. When given a URL/Git repository\nor a path to a local Quokka template, quokka will ask for the required values\nin an interactive way except if an inpute file is given to the CLI.\n\nUsage:\n  qk [template] [output] \u003coptions\u003e [flags]\n  qk [command]\n\nAvailable Commands:\n  help        Help about any command\n  new         Create a new quokka template\n  version     Show build and version\n\nFlags:\n      --debug           Enable or disable debug mode\n      --git.depth int   depth of git clone in case of git provider (default 1)\n  -h, --help            help for qk\n  -i, --input string    specify an input values file to automate template rendering\n  -k, --keep            do not delete the template when operation is complete\n  -o, --output string   specify the directory where the template should be downloaded or cloned\n  -p, --path string     specify if the template is actually stored in a sub-directory of the downloaded file\n  -e, --set strings     specify values on the command line\n  -y, --yes             Automatically accept\n\nUse \"qk [command] --help\" for more information about a command.\n```\n\n## Keeping the template\n\nWhen cloning a template, Quokka will create a temporary\ndirectory and delete it once the operation completes. If you want to keep\nthe template (to play with it, or simply to keep a copy), make sure you pass\nthe `-k/--keep` option. This option pairs well with the `-o/--output` option\nwhich defines where the template should be downloaded/cloned.\n\n## Input file\n\nThe rendering of a Quokka template can be automated if the template was designed\nwith this in mind and if an input file is provided on the command line.\n\nSince there is no clear way for specifying overriding values (for example a\nvariable that applies to a single file and overrides an already existing\nvariable in the root config), the input values will also fill the overriding\nvariables.\n\nThe format of the input file is also yaml. The following example demonstrates\nhow an input file could be used:\n\n`.quokka.yml`\n```yaml\nname: \"Quokka Template\"\ndescription: \"New Quokka Template\"\nversion: \"0.1.0\"\nvariables:\n  slack:\n    confirm: true\n    prompt: \"Add Slack integration?\"\n    variables:\n      channel:\n        required: true\n      webhook:\n        required: true\n```\n\n`input.yml`\n```yaml\nslack: true\nslack_channel: \"#mychan\"\nslack_webhook: \"complexurl\n```\n\nIf this input file is given to Quokka, it won't prompt for these three\nvariables, thus requiring no input from the user to render the template.\n\n## Set\n\nAdditionally, you can provide Quokka with the `-e/--set` flag (multiple time if\nyou wish). This works the same way as the input file but has a higher priority,\nmeaning that if you pass both an input file and a `-e` flag that defines a\nvariable, the one passed on the command line will have a higher priority.\n\nThe `--set` flags work by providing it with a `key=value` style kind of string.\nIf we take the example above using the input file, we can effectively replace\nthe `slack_channel` variable by doing so:\n\n```sh\n$ qk template/ output -i input.yml --set \"slack_channel=#anotherchan\"\n$ # Or\n$ qk template/ output -i input.yml -e \"slack_channel=#anotherchan\"\n```\n\n## Examples\n\n```sh\n$ # Clone the repository and execute the template that is located in _example/license\n$ qk git@github.com:Depado/quokka.git output --path _example/license\n$ # Clone the template in a specific directory, render it in a specific directory and keep the template\n$ qk git@github.com:Depado/quokka.git myamazingproject --path _example/cleanarch --keep --output \"template\"\n$ # Reuse the downloaded template\n$ qk template/ myotherproject\n$ # Pass an input file to Quokka\n$ qk template/ output -i in.yml\n```\n\n# Template Creation\n\n## New command\n\nIf `quokka` is installed, simply run `quokka new \u003cpath\u003e`. This will ask for\nbasic information such as the template name, description and version with some\nsane defaults (version number for example is set to `0.1.0` by default).\nYou can also pass these values as flags on the command line.\n\nThis command will check if the output directory and a `.quokka.yml` file already\nexist. This command is in charge of creating a new directory and creating the\ninitial `.quokka.yml` file with those basic information, helping you getting\nstarted with Quokka template development.\n\n\u003cdetails\u003e\u003csummary\u003eCommand Line Help\u003c/summary\u003e\n\n```\n$ qk new --help\nCreate a new quokka template\n\nUsage:\n  qk new [output] \u003coptions\u003e [flags]\n\nFlags:\n  -d, --description string   description of the new template\n  -h, --help                 help for new\n  -n, --name string          name of the new template\n  -v, --version string       version of the new template\n\nGlobal Flags:\n      --debug   Enable or disable debug mode\n  -y, --yes     Automatically accept\n```\n\u003c/details\u003e\n\n## The root `.quokka.yml` file\n\nTo configure your template, place a `.quokka.yml` at the root of your template.\nThis is called the root configuration, and should contain some information about\nyour template such as its name, its version and a description.\n\nIt can also contain overrides for delimiters in the templates (defaults being\nthe go-style `{{ .var }}`) and variables.\n\n```yaml\nname: \"Example Quokka Template\"\nversion: \"0.1.0\"\ndescription: \"An example template to show how quokka works\"\n```\n\n## Variable declaration\n\nYou can add a `variables` section to your root configuration (or to any\n`.quokka.yml` file, or directly inline in your template files, see below) to\ndefine the variables you want your user to fill in. There are three types of\ninput you can use:\n\n### Simple Input\n\nIf you just specify the name of your variable, it will result in a simple input.\n\n```yaml\nvariables:\n  name:\n```\n\n### Selection\n\n```yaml\nvariables:\n  license:\n    values: [\"MIT\", \"Apache License 2.0\", \"BSD 3\", \"FreeBSD\", \"GPL\", \"LGPL\", \"WTFPL\", \"None\"]\n```\nThis will result in a selection input where the user can choose one of the\nprovided choices.\n\n### Boolean/Confirmation\n\n```yaml\nvariables:\n  test:\n    confirm: true\n```\nIf you're using the `confirm` keyword, it will generate a simple yes/no input.\nThe value you give that `confirm` key becomes the default value.\n\n### Other options and help\n\nYou can also help your users by changing the prompt, adding a help text or\nproviding a default value:\n\n```yaml\nvariables:\n  license:\n    values: [\"MIT\", \"Apache License 2.0\", \"BSD 3\", \"FreeBSD\", \"GPL\", \"LGPL\", \"WTFPL\", \"None\"]\n    prompt: Which license do you want for your project?\"\n    help: \"License file that will be added to your project\"\n    default: \"MIT\"\n  name:\n    default: amazingproject\n    prompt: \"What's the name of your project?\"\n    help: \"Used to render the README file and various configuration files\"\n```\n\n### Validation\n\nYou can mark any variable as required using the `required` keyword:\n\n```yaml\nvariables:\n  name:\n    default: amazingproject\n    prompt: \"What's the name of your project?\"\n    help: \"Used to render the README file and various configuration files\"\n    required: true\n```\n\nThis will prevent the user from rendering your template with missing variables.\nNote that if you specified a default value for an input, it becomes impossible\nto not fill in that value. So the validator becomes obsolete.\n\n### Sub Variables\n\nIt's not uncommon to ask for additional information when the user answered yes\nor filled in a variable. Thus, each variable can have its own variables:\n\n```yaml\nvariables:\n  slack:\n    confirm: true\n    prompt: \"Add Slack integration?\"\n    variables:\n      channel:\n        required: true\n        prompt: \"In which Slack channel should the result be posted?\"\n      webhook:\n        required: true\n        help: \"See https://api.slack.com/incoming-webhooks for more information\"\n        prompt: \"Provide the Slack webhook URL:\"\n```\n\nIn the example above we ask the user if he wants a Slack integration. If he\nanswers yes to that, then we'll ask him about the Slack channel and the webhook\nURL. Otherwise we won't bother him with these details since they won't be used\nin our template rendering.\n\nThe sub variables can be accessed in your templates with the form `.parent_sub`.\nIn this case, `.slack_channel` and `.slack_webhook`.\n\n## Standard `.quokka.yml` files\n\nIf you place a `.quokka.yml` file in a sub-directory of your template, this\nfile will apply recursively to all the elements inside that directory and its\nown sub-directories, meaning that you can override some variables, add new ones,\nmodify the delimiters, or completely ignore an entire directory.\n\nFor example you can completely ignore a directory:\n\n```\n└──── change\n    ├── override.go\n    └── .quokka.yml\n```\n\n```yaml\ncopy: true\n```\n\nIn this case, the file `override.go` won't be rendered (but will simply be\ncopied to the output directory). This would apply for every sub-directory,\nexcept if a directory contains a `.quokka.yml` telling otherwise, or a\nfile with an inline configuration. The `ignore` option can also be used to\ncompletely ignore a file or a directory.\n\n```yaml\nignore: true\n```\n\n## Per-file configuration\n\nYou can also configure individual files by adding a front matter at the top\nof the file (that will obviously be removed when rendered).\n\nLet's say I have a file that I don't want to render but simply copy to the\noutput directory:\n\n```\n---\ncopy: true\n---\n# This shouldn't be rendered at all !\n```\n\nYou can even add per-file variables, or modify the delimiters. In fact, it's\nlike an inline `.quokka.yml` that applies to a single file.\n\nSupported instructions are as follows:\n\n- `if: condition`: Conditional rendering using an [expr](https://expr.medv.io/docs/Language-Definition)\n  expression that must return a boolean value\n- `copy: true`: Do not attempt to render the file and simply copy it to its\n  destination\n- `delimiters: [\"[[\", \"]]\"]`: Change the delimiters used for template rendering.\n  This can be useful for files that already are templates or use extensively the\n  `{}` chars\n- `rename: newname`: Rename the file to this new name once rendered\n- `ignore: true`: Completely ignore the file (no render, no copy)\n\n## Conditional Rendering/Copy\n\nYou may want some files to not be copied or rendered according to what the user\nanswers to your prompt. You can use the `if` key (in a `.quokka.yml`\nor inline in a file), with the name of one of your variables. For example if\nyou have a variable defined like this in your root config:\n\n```yaml\nvariables:\n  drone:\n    prompt: \"Do you want to add a Drone config file?\"\n    confirm: true\n```\n\nYou can then add this at the top of the file:\n\n```\n---\nif: drone\n---\nworkspace:\n  base: /go\n...\n```\n\nThis file will be rendered if, and only if, the user answered yes to that\nquestion. Note that `if` and `copy` can work together if you just want\nto copy the file and not render it.\n\n# ToDo\n\n- [ ] Ignore file list in `.quokka.yml`\n  - Use case: Add a `README.md` to document the template along with\n    `README.md.tmpl` with a `rename` directive. This would avoids the front-matter\n    in the template documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDepado%2Fquokka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDepado%2Fquokka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDepado%2Fquokka/lists"}