diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..8b2a513
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,19 @@
+# The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
\ No newline at end of file
diff --git a/README.md b/README.md
index cfae0ab..85444b7 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,12 @@
# Stamp
-Stamp helps you to generate common repository files like `README.md`, `LICENSE`, `.gitignore`, `Dockerfile` etc.
+Stamp generate files by applying data to templates.
+
+## Use-cases:
+
+* Generate common repository files like README.md, LICENSE, .gitignore, etc (by combining stamp with [metaculous](https://github.com/linkorb/metaculous))
+* Static site generator
+* Documentation generator
## Installation
@@ -10,22 +16,19 @@ Stamp helps you to generate common repository files like `README.md`, `LICENSE`,
vendor/bin/stamp --help
-## Workflow:
+## How does it work?
-### 1. Load `stamp.yml` configuration:
+When you run `stamp generate`, Stamp will look for it's configuration in a file called `stamp.yaml` in the current directory. You can also pass a specify config file using `-c`.
-Stamp looks for a file called `stamp.yml` in your project root (or you can specify one using `-c`)
-and json file `metaculous.json` generated by linkorb/metaculous (or you can specify one using `-j`)
+Additionally, stamp loads data from a file called `data.json`, or you can specify one using `-j`.
-The config defines:
+For example `stamp.yaml` and `data.json` files, please check the `example/` directory.
-1. Project specific variables (i.e. license, project name, etc)
-2. A list of files to be generated. Each file can have a name, template (file or url) and a set of variables, that override the project variables for this file only.
-
+Stamp will then loop through the `templates` defined in the config file, and use the template files defined by the `src` key, and generate the file defined by the `dest` key.
-### 2. Generate files
+By specifying an `items` key, one template may be applied multiple times, resulting in multiple output files.
-Stamp loops through all the files defined in `stamp.yml`, loads their template, inserts the collected data, and saves the file to disk.
+By specifying a `variables` key, the variables at the template level will get merged with the project level variables before being passed to the template, allowing you to override/add variables at the template level.
## stamp.yml example:
@@ -33,54 +36,55 @@ Here's a simple example `stamp.yml` file:
```yml
variables:
- project:
- title: Hello world
+ title: Hello world
+ license: mit
files:
- README.md:
- template: stamp/README.md.twig
+ - src: stamp/README.md.twig
+ dest: README.md
variables:
- title: Hello world
- blocks:
- - "@doc/intro.md"
- - "@doc/installation.md"
+ title: Hello world README file
- LICENSE.md:
- template: https://raw.githubusercontent.com/IQAndreas/markdown-licenses/master/mit.md
+ - src: https://raw.githubusercontent.com/IQAndreas/markdown-licenses/master/{{ license }}.md
+ dest: LICENSE
- CONTRIBUTING.md:
- template: https://raw.githubusercontent.com/gitlabhq/gitlabhq/master/CONTRIBUTING.md
+ - src: https://raw.githubusercontent.com/gitlabhq/gitlabhq/master/CONTRIBUTING.md
+ dest: CONTRIBUTING.md
```
Simply type `stamp generate` (or `vendor/bin/stamp generate`) in the root of your project, and the listed files will be (re)generated based on their templates.
-Using URLs as templates allow you to manage your templates in one location, making it easy to update your projects based on updated templates.
+Using URLs as templates allow you to manage your templates in one location (a git repository), making it easy to update your projects based on updated templates.
+
+Stamp supports multiple template languages/engines, which will be used based on the template file (src) file extension:
+
+* `.twig`: Use the [Twig](https://twig.symfony.com/) template language
+* `.hbs`, `.handlebars`: Use the [Handlebars](https://handlebarsjs.com/) template language (powered by [LightnCandy](https://github.com/zordius/lightncandy))
+* `.mustache`: Use the [Mustache](https://mustache.github.io/) template language (powered by [LightnCandy](https://github.com/zordius/lightncandy))
+
+## Functions
+
+In `stamp.yaml`, you define `src`/`dest` filenames and `items` variables.
+These keys all support "expressions" in which you could optionally use a set of functions to apply to variables.
+
+* `strtolower`: lowercase the variable
+* `dict`: Convert a key/value dictionary into an array of `item.key` and `item.value` items.
-When the template files end in `.twig`, Stamp will use Twig to process the template based on the variables defined on the file and globally on the project.
+More functions can easily be registered in the constructor of `src/Generator.php`.
## Development / debugging:
-The `examples/` directory contains a collection of common files. While developing analyzers, you can run `./bin/stamp generate -c examples/full-project/stamp.yml` to run stamp in the context of the `examples/full-project/` directory.
-
-You can use the following command to debug the data that will be injected into any templates (including the output from the analyzers):
-
- ./bin/stamp generate -c examples/full-project/stamp.yml
-
-## Todo:
-
-* [x] Analyzer for `Dockerfile`: Simply define a variable if it exists.
-* [x] Analyzer for `docker-compose.yml`: Import the YAML as-is. Can be used to list defined containers.
-* [x] Analyzer for `Makefile`: Import the targets + comments, using the regex in `examples/full-project/Makefile`
-* [x] Analyzer for `bower.json`: Import the JSON as-is. Can be used to list jobs
-* [x] Analyzer for `.env.dist`: Import variables, their default values, and comments (line before the variable)
-* [x] Analyzer for `.circleci/config.yml`: Import the YAML as-is. Can be used to list jobs
-* [x] Analyzer for `.editorconfig`: Simply define a variable if it exists.
-* [x] Analyzer for `schema.xml`: Used to document schema
-* [x] Analyzer for `routes`: Used to document routes. Looks for `app/config/routes.yml` (Radvance)
-* [x] Analyzer for `routes`: Used to document routes. Uses symfony `bin/console debug:router --format JSON` to import route data
-* [x] Analyzer for `doctrine-schema`: Find a way to load doctrine schema into an array for entity documentation
-* [x] Analyzer for `fixtures`: (Haigha). Simply define a variable if it exists.
-* [x] Analyzer for `anonymizer.yml`: Simply define a variable if it exists.
-* [x] Analyzer for `github`: Request repository data like contributors, title, etc.
-* [x] Allow to use project variables in template filenames/urls (i.e. to fetch the proper license file)
-* [x] Allow to use either twig or handlebars templates (using `zordius/lightncandy`)
+The `examples/` directory contains an example configuration (`stamp.yaml`), data file (`data.json`) and template files.
+
+## License
+
+MIT. Please refer to the [license file](LICENSE) for details.
+
+## Brought to you by the LinkORB Engineering team
+
+Hello world
+
+
+
Hello world
+
+
+
Tags:
+
+
+
+
{{ title }}
+
+ Tags:
+
+
+ {{ title }}
+
+
+ {% block body %}{% endblock body %}
+
+
+
\ No newline at end of file
diff --git a/example/templates/index.md.twig b/example/templates/index.md.twig
new file mode 100644
index 0000000..1015a18
--- /dev/null
+++ b/example/templates/index.md.twig
@@ -0,0 +1,12 @@
+{{ title }}
+===========
+
+This is the README of {{ title }}
+
+License: {{ license }}
+
+## Products:
+
+{% for code, product in products %}
+* [{{ product.title }}](product.{{ code }}.md)
+{% endfor %}
\ No newline at end of file
diff --git a/example/templates/product.md.hbs b/example/templates/product.md.hbs
new file mode 100644
index 0000000..2a56eda
--- /dev/null
+++ b/example/templates/product.md.hbs
@@ -0,0 +1,9 @@
+# product "{{ item.value.title }}" ({{ item.key }})
+
+
- author_display_name:
- created_at: fake('dateTime'))>
- message:
- status:
diff --git a/examples/full-project/package.json b/examples/full-project/package.json
deleted file mode 100644
index 22730a9..0000000
--- a/examples/full-project/package.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
- "name": "example-react",
- "version": "0.1.0",
- "private": true,
- "dependencies": {
- "react": "^16.4.2",
- "react-dom": "^16.4.2",
- "react-scripts": "1.1.4"
- },
- "scripts": {
- "start": "react-scripts start",
- "build": "react-scripts build",
- "test": "react-scripts test --env=jsdom",
- "eject": "react-scripts eject"
- }
-}
\ No newline at end of file
diff --git a/examples/full-project/schema.xml b/examples/full-project/schema.xml
deleted file mode 100644
index e69de29..0000000
diff --git a/examples/full-project/stamp.yml b/examples/full-project/stamp.yml
deleted file mode 100644
index e0cf81a..0000000
--- a/examples/full-project/stamp.yml
+++ /dev/null
@@ -1,28 +0,0 @@
-variables:
- project:
- title: Hello world
- license: "{{ analyzer['composer.json']['license'] }}"
- radvance:
- schema:
- references:
- username: user_data
-
-files:
- README.md:
- template: README.md.twig # In practice a remote URL would be used here
- variables: # Variable overrides specific to this file only
- title: Hello world
- blocks: # Include custom documentation blocks with local or remote content
- - "doc/intro.md"
- - "doc/installation.md"
- - "https://raw.githubusercontent.com/rodrigorm/phpqa-make/master/Makefile"
- INSTALL.md:
- template: INSTALL.md.handlebars
-
- LICENSE.md:
- template: "https://raw.githubusercontent.com/linkorb/stamp-templates/master/license/{{ analyzer['composer.json']['license'] | lower }}.md"
-
- # CONTRIBUTING.md:
- # template: https://example.com/stamps/CONTRIBUTING.md.twig
- # Dockerfile:
- # template: https://example.com/stamps/Dockerfile.twig
diff --git a/src/Command/GenerateCommand.php b/src/Command/GenerateCommand.php
index 403d22e..e2ff478 100644
--- a/src/Command/GenerateCommand.php
+++ b/src/Command/GenerateCommand.php
@@ -23,20 +23,20 @@ protected function configure()
$this
->setName('generate')
- ->setDescription('Generate files from stamp.yml')
+ ->setDescription('Generate files from stamp.yaml')
->addOption(
'config',
'c',
InputOption::VALUE_REQUIRED,
'Configuration file to use',
- getcwd() . '/stamp.yml'
+ getcwd() . '/stamp.yaml'
)
->addOption(
'json',
'j',
InputOption::VALUE_REQUIRED,
- 'Json file to use (used by default - metaculous.json)',
- getcwd() . '/metaculous.json'
+ 'JSON file to use (used by default - data.json)',
+ getcwd() . '/data.json'
)
;
}
@@ -54,18 +54,21 @@ protected function execute(InputInterface $input, OutputInterface $output)
$output->writeLn("Using configuration file: " . $configFilename);
$projectLoader = new YamlProjectLoader();
$project = $projectLoader->loadFile($configFilename);
+
$jsonFilename = $input->getOption('json');
$json = [];
if (!file_exists($jsonFilename)) {
- throw new RuntimeException("Json file not found: " . $jsonFilename);
+ throw new RuntimeException("JSON file not found: " . $jsonFilename);
}
$jsonData = json_decode(file_get_contents($jsonFilename), true);
if (json_last_error() !== JSON_ERROR_NONE) {
- throw new RuntimeException("Error parsing json file: " . $jsonFilename);
+ throw new RuntimeException("Error parsing JSON file: " . $jsonFilename);
}
- $project->setAnalyzedData($jsonData);
-
+ //TODO: merge jsonData with main project data
+ $variables = array_merge_recursive($jsonData, $project->getVariables());
+ $project->setVariables($variables);
+ // print_r($project); exit();
$generator = new Generator($project);
$generator->generate();
}
diff --git a/src/Generator.php b/src/Generator.php
index 1a89a68..a04a7b4 100644
--- a/src/Generator.php
+++ b/src/Generator.php
@@ -3,83 +3,147 @@
namespace Stamp;
use Stamp\Model\Project;
-use Stamp\Model\File;
+use Stamp\Model\Template;
use LightnCandy\LightnCandy;
+use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
use Twig_Environment;
use Twig_Loader_String;
+use Twig_Loader_Filesystem;
+
+use RuntimeException;
class Generator
{
private $twig;
+ private $expressionLanguage;
public function __construct(Project $project)
{
$this->project = $project;
- $this->twig = new Twig_Environment(new Twig_Loader_String());
+ $loader = new Twig_Loader_String();
+ //$loader->addPath($project->getBasePath(), 'project');
+ $loader = new Twig_Loader_Filesystem($project->getBasePath());
+
+
+ $this->twig = new Twig_Environment($loader);
+ $this->expressionLanguage = new ExpressionLanguage();
+
+ $this->expressionLanguage->register(
+ 'dict',
+ function ($items) {},
+ function ($arguments, $items) {
+ $res = [];
+ foreach ($items as $key => $value) {
+ $res[] = [
+ 'key' => $key,
+ 'value' => $value,
+ ];
+ }
+ return $res;
+ }
+ );
+
+ $this->expressionLanguage->register(
+ 'strtolower',
+ function ($items) {},
+ function ($arguments, $str) {
+ return strtolower($str);
+ }
+ );
+
}
public function generate()
{
- foreach ($this->project->getFiles() as $file) {
- $this->generateFile($file);
+ foreach ($this->project->getTemplates() as $template) {
+ $this->generateTemplate($template);
}
}
-
- protected function process(&$item, &$key)
+
+ public function generateTemplate(Template $template)
{
- if ($item[0]=='@') {
- $filename = substr($item, 1);
- $item = $this->loadString($filename);
+ $items = $template->getItems();
+ $variables = $this->project->getVariables();
+ $variables = array_merge($variables, $template->getVariables());
+ if ($items) {
+ if (is_string($items)) {
+ if ($items[0]=='{') {
+ $expression = trim($items, '{} ');
+
+ $items = $this->expressionLanguage->evaluate($expression, $variables);
+ }
+ }
+ }
+ if (!$items) {
+ $items = [
+ 'default'
+ ];
}
+ foreach ($items as $item) {
+ $variables['item'] = $item;
+ $src = $template->getSrc();
+ $dest = $template->getDest();
+ $src = $this->interpolate($src, $variables);
+ $dest = $this->interpolate($dest, $variables);
+ $content = $this->getContent($src);
+
+ $extension = pathinfo($src, PATHINFO_EXTENSION);
+ $out = $this->renderContent($content, $extension, $variables);
+
+ $destFilename = $this->normalizeFilename($dest);
+ $destPath = dirname($destFilename);
+
+ if (!file_exists($destPath)) {
+ mkdir($destPath, 0777, true);
+ }
+ file_put_contents(
+ $destFilename,
+ $out
+ );
+ }
+
+
}
- public function generateFile(File $file)
- {
- file_put_contents(
- $this->project->getBasePath() . '/' . $file->getName(),
- $this->renderFile($file)
- );
+ public function interpolate(string $str, array $variables) {
+ preg_match_all('/\{\{(.*?)\}\}/i', $str, $matches, PREG_PATTERN_ORDER);
+ for ($i = 0; $i < count($matches[1]); $i++) {
+ $expression = trim($matches[1][$i]);
+
+ // turn sub-keys into objects for dot-notation access in expressions
+ $variables2 = [];
+ foreach ($variables as $k=>$v) {
+ $variables2[$k] = json_decode(json_encode($v));
+ }
+ // evaluate
+ $res = $this->expressionLanguage->evaluate($expression, $variables2);
+ $str = str_replace($matches[0][$i], $res, $str);
+ }
+ return $str;
}
- public function renderFile(File $file): string
+ public function renderContent(string $content, string $extension, array $variables): string
{
- $analyzed = ['analyzer' => $this->project->getAnalyzedData()];
- $config = $this->interpolate($this->project->getConfig(), $analyzed);
- $fileConfig = $this->interpolate($file->getVariables(), $analyzed);
- $blocks = isset($fileConfig['blocks']) ? array_map(
- function($block) {
- return $this->loadString($block);
- }, $fileConfig['blocks']
- ) : [];
-
- $data = array_merge_recursive(
- $analyzed,
- $config,
- $fileConfig,
- ['blocks' => $blocks]
- );
-
- $templateStringTemplate = $this->twig->createTemplate($file->getTemplate());
- $templateString = $this->loadString($templateStringTemplate->render($data));
-
- if ($file->hasTemplateExtension('twig')) {
- $template = $this->twig->createTemplate($templateString);
- return $template->render($data);
- } else if ($file->hasTemplateExtension('handlebars')) {
- $renderWith = LightnCandy::FLAG_HANDLEBARSJS;
- } else if ($file->hasTemplateExtension('hbs')) {
- $renderWith = LightnCandy::FLAG_HANDLEBARSJS;
- } else if ($file->hasTemplateExtension('mustache')) {
- $renderWith = LightnCandy::FLAG_MUSTACHE;
- } else {
- return $templateString;
+ switch ($extension) {
+ case 'twig':
+ $template = $this->twig->createTemplate($content);
+ return $template->render($variables);
+ case 'hbs':
+ case 'handlebars':
+ $renderWith = LightnCandy::FLAG_HANDLEBARSJS;
+ break;
+ case 'mustache':
+ $renderWith = LightnCandy::FLAG_MUSTACHE;
+ break;
+ default:
+ return $content;
}
if (isset($renderWith)) {
$t = LightnCandy::compile(
- $templateString,
+ $content,
[
'flags' => $renderWith,
'helpers' => [
@@ -100,34 +164,28 @@ function($block) {
);
$renderer = LightnCandy::prepare($t);
- return $renderer($data, []);
+ return $renderer($variables, []);
}
+ return null;
}
- public function interpolate(array $config, array $analyzerResults): array {
- $data = array_merge_recursive($config, $analyzerResults);
- $twig = new \Twig_Environment(new \Twig_Loader_String());
-
- array_walk_recursive($config, function(&$value, $key) use ($data, $twig) {
- $template = $twig->createTemplate($value);
- $value = $template->render($data);
- });
-
- return $config;
- }
- public function loadString($template)
+ public function normalizeFilename(string $filename): string
{
- if (substr($template, 0, 4)=='http') {
- // Load over HTTP
- return file_get_contents($template);
+ if (substr($filename, 0, 4)=='http') {
+ return $filename;
}
- if (substr($template, 0, 1)=='/') {
+ if (substr($filename, 0, 1)=='/') {
// absolute path
- return file_get_contents($template);
+ return $filename;
}
-
- // relative path
- return file_get_contents($this->project->getBasePath() . '/' . $template);
+
+ return $this->project->getBasePath() . '/' . $filename;
+ }
+
+ public function getContent(string $filename): string
+ {
+ $filename = $this->normalizeFilename($filename);
+ return file_get_contents($filename);
}
}
diff --git a/src/Loader/ArrayProjectLoader.php b/src/Loader/ArrayProjectLoader.php
index 3e79c3d..5d81426 100644
--- a/src/Loader/ArrayProjectLoader.php
+++ b/src/Loader/ArrayProjectLoader.php
@@ -3,20 +3,19 @@
namespace Stamp\Loader;
use Stamp\Model\Project;
-use Stamp\Model\File;
+use Stamp\Model\Template;
class ArrayProjectLoader
{
- public function load($data, $basePath)
+ public function load(array $config, $basePath)
{
- $project = new Project($basePath, $data);
+ $project = new Project($basePath, $config['variables'] ?? []);
- foreach ($data['files'] ?? [] as $name => $fileData) {
- $template = $fileData['template'] ?? null;
- $variables = $fileData['variables'] ?? [];
- $file = new File($name, $template, $variables);
- $project->addFile($file);
+ foreach ($config['templates'] ?? [] as $templateConfig) {
+ $template = Template::buildFromConfig($templateConfig);
+ $project->addTemplate($template);
}
+
return $project;
}
}
diff --git a/src/Model/File.php b/src/Model/File.php
deleted file mode 100644
index 25017ed..0000000
--- a/src/Model/File.php
+++ /dev/null
@@ -1,43 +0,0 @@
-name = $name;
- $this->template = $template;
- $this->variables = $variables;
- }
-
- public function getName()
- {
- return $this->name;
- }
-
- public function getTemplateExtensions(): array
- {
- $extensions = explode('.', $this->getTemplate());
- return array_splice($extensions, 1);
- }
-
- public function hasTemplateExtension(string $ext): bool
- {
- return array_search($ext, $this->getTemplateExtensions()) !== false;
- }
-
- public function getTemplate()
- {
- return $this->template;
- }
-
- public function getVariables()
- {
- return $this->variables;
- }
-}
diff --git a/src/Model/Project.php b/src/Model/Project.php
index 7726da3..04eaff4 100644
--- a/src/Model/Project.php
+++ b/src/Model/Project.php
@@ -4,24 +4,24 @@
class Project
{
- protected $files = [];
- protected $config = [];
- protected $analyzedData = [];
+ protected $templates = [];
+ protected $variables = [];
protected $basePath;
- public function __construct($basePath, $config = [])
+ public function __construct($basePath, $variables = [])
{
$this->basePath = $basePath;
- $this->config = $config;
+ $this->variables = $variables;
}
public function getVariables(): array
{
- return $this->config['variables'] ?? [];
+ return $this->variables ?? [];
}
- public function getConfig(): array {
- return $this->config;
+ public function setVariables(array $variables): void
+ {
+ $this->variables = $variables;
}
public function getBasePath()
@@ -29,49 +29,17 @@ public function getBasePath()
return $this->basePath;
}
- public function addFile(File $file)
- {
- $this->files[$file->getName()] = $file;
- }
- public function getFiles()
+ public function addTemplate(Template $template)
{
- return $this->files;
+ $this->templates[] = $template;
}
- /**
- * @param array $analyzedData
- */
- public function setAnalyzedData(array $analyzedData): void
+ public function getTemplates()
{
- $this->analyzedData = $analyzedData;
- }
-
- /**
- * @return array
- */
- public function getAnalyzedData(): array
- {
- return $this->analyzedData;
+ return $this->templates;
}
public function getFilepath(string $filename): string {
return $this->getBasePath() . '/' . $filename;
}
-
- public function hasConsole(): bool
- {
- return file_exists(
- $this->getFilepath('bin/console')
- );
- }
-
- public function console(string $cmd): ?string {
- $console = $this->getFilepath('bin/console');
-
- if (!$this->hasConsole()) {
- return null;
- }
-
- return shell_exec("$console $cmd");
- }
}
diff --git a/src/Model/Template.php b/src/Model/Template.php
new file mode 100644
index 0000000..b8f7fe7
--- /dev/null
+++ b/src/Model/Template.php
@@ -0,0 +1,45 @@
+src = $config['src'] ?? null;
+ $file->dest = $config['dest'] ?? null;
+ $file->items = $config['items'] ?? null;
+ $file->variables = $config['variables'] ?? [];
+ return $file;
+ }
+
+ public function getSrc(): string
+ {
+ return $this->src;
+ }
+
+ public function getDest(): string
+ {
+ return $this->dest;
+ }
+
+ public function getVariables(): array
+ {
+ return $this->variables;
+ }
+
+ public function getItems()
+ {
+ return $this->items;
+ }
+}
diff --git a/tests/Model/FileTest.php b/tests/Model/FileTest.php
deleted file mode 100644
index 2d70b1b..0000000
--- a/tests/Model/FileTest.php
+++ /dev/null
@@ -1,19 +0,0 @@
-assertEquals(['html', 'twig'], $file->getTemplateExtensions());
-
- $this->assertTrue($file->hasTemplateExtension('html'));
- $this->assertTrue($file->hasTemplateExtension('twig'));
- $this->assertFalse($file->hasTemplateExtension('php'));
- }
-}
+
+## Tags:
+
+* fruit
+* red
diff --git a/example/output/product.kiwi.md b/example/output/product.kiwi.md
new file mode 100644
index 0000000..856e603
--- /dev/null
+++ b/example/output/product.kiwi.md
@@ -0,0 +1,8 @@
+# product "Kiwi" (kiwi)
+
+
+
+## Tags:
+
+* fruit
+* green
diff --git a/example/output/product.palmtree.md b/example/output/product.palmtree.md
new file mode 100644
index 0000000..028b2b6
--- /dev/null
+++ b/example/output/product.palmtree.md
@@ -0,0 +1,8 @@
+# product "Palmtree" (palmtree)
+
+
+
+## Tags:
+
+* flora
+* green
diff --git a/example/output/product.rose.md b/example/output/product.rose.md
new file mode 100644
index 0000000..184f2a7
--- /dev/null
+++ b/example/output/product.rose.md
@@ -0,0 +1,8 @@
+# product "Rose" (rose)
+
+
+
+## Tags:
+
+* flora
+* red
diff --git a/example/stamp.yaml b/example/stamp.yaml
new file mode 100644
index 0000000..14d9b54
--- /dev/null
+++ b/example/stamp.yaml
@@ -0,0 +1,42 @@
+variables:
+ license: MIT
+ title: Hello world
+ # license: "{{ analyzer['composer.json']['license'] }}"
+ radvance:
+ schema:
+ references:
+ username: user_data
+
+templates:
+ - src: templates/index.md.twig
+ dest: "output/index.md"
+
+ variables: # Variable overrides specific to this template only
+ title: My Hello world
+ # blocks: # Include custom documentation blocks with local or remote content
+ # - "templates/intro.md"
+ # - "https://raw.githubusercontent.com/rodrigorm/phpqa-make/master/Makefile"
+
+ - src: templates/author.md.mustache # In practice a remote URL would be used here
+ dest: "output/author.{{ item.name }}.md"
+ items: # demonstrate template-specific items
+ - name: joe
+ email: joe@example.com
+ - name: alice
+ email: alice@example.com
+
+ - src: templates/product.md.hbs
+ dest: "output/product.{{ item.key }}.md"
+ items: "{{ dict(products) }}" # create one output (dest) file per item in the dictionary
+
+ - src: "https://raw.githubusercontent.com/linkorb/stamp-templates/master/license/{{ strtolower(license) }}.md"
+ dest: "output/LICENSE" # Output a single file
+
+ - src: templates/about.html.twig
+ dest: "output/about.html" # HTML / layout example
+
+ # - src: https://example.com/stamps/CONTRIBUTING.md.twig
+ # dest: output/CONTRIBUTING.md.twig
+
+ # - src: https://example.com/stamps/Dockerfile.twig
+ # dest: Dockerfile.twig
\ No newline at end of file
diff --git a/example/templates/about.html.twig b/example/templates/about.html.twig
new file mode 100644
index 0000000..ebd2982
--- /dev/null
+++ b/example/templates/about.html.twig
@@ -0,0 +1,15 @@
+{% extends 'templates/base.html.twig' %}
+
+{% block body %}
+