yml2html 0.2.0

Transforms yml with templates into html

yml2html

Yml2Html is a Dart package which functions as a pub transformer.

Transformers can be used in pubspec.yaml to convert assets before deploying.

Yml2Html combines templates (*.tmpl.html), ymlHtml files (*.yml.html or *.out.yml.html) and pure yml files (.yml) into html output.

It's essentially a static site generator, but without all the complicated settings, just yml with templates.

Yml2Html has no config files or build server, just one transformer that does all the work for you.

---

Dart Pub: https://pub.dartlang.org/packages/yml2html

Github: https://github.com/diederik-dev/yml2html

---

Templates

Templates are very simple:

• templates are html files in your web or lib directory with a double extension: <template-name>.tmpl.html
• templates contain mustaches (the {{ ... }} and {{{ ... }}} tags) which make the html file function like a template
• the templates can be used by yml files and ymlHtml files

YmlHtml files

There are two flavors of ymlHtml files: <filename>.out.yml.html and <filename>.yml.html

<filename>.yml.html is the helper version: some yml in a yml block and referable html blocks

<filename>.out.yml.html is the output version, it does exactly the same as <filename>.yml.html, but outputs to the build folder (the extension becomes .html) and can include helper files.

YAML files

YAML or YML, both work.

Pure .yml files (no referable html blocks) can be used as helpers as well, like the <filename>.yml.html files.

Referring to html blocks

Example

Lets look at an example:

<!--@formatter:off-->
<!--~~~~%YAML~~~~~
testyml: test! ~%~sidecontent
~~~~/YAML~~~~-->
<!--@formatter:on-->
<!--~~~~#sidecontent~~~~-->

<ul>
    <li>Morbi in sem quis dui placerat ornare. Pellentesque odio nisi, euismod in, pharetra a, ultricies in, diam. Sed
        arcu. Cras consequat.
    </li>


    <li>Praesent dapibus, neque id cursus faucibus, tortor neque egestas augue, eu vulputate magna eros eu erat. Aliquam
        erat volutpat. Nam dui mi, tincidunt quis, accumsan porttitor, facilisis luctus, metus.
    </li>
    <li>Phasellus ultrices nulla quis nibh. Quisque a lectus. Donec consectetuer ligula vulputate sem tristique cursus.
        Nam nulla quam, gravida non, commodo a, sodales sit amet, nisi.
    </li>
    <li>Pellentesque fermentum dolor. Aliquam quam lectus, facilisis auctor, ultrices ut, elementum vulputate, nunc.
    </li>
</ul>


<!--~~~~/~~~~-->

Notes:

It looks ugly, but it works very well.

Enclosing the open (~~~~#<name_without_spaces>~~~~) and close (~~~~/~~~~) tags with comments is optional, but prevents mixing up HTML and YML.

It is recommended to use the <!--@formatter:on--> and <!--@formatter:on--> comments to prevent your WebStorm and other IDEs to format the YAML as HTML. (These tags are changeable in most IDEs and might not be activated by default)

~%~<name_without_spaces> refers to a html block, started with: ~~~~#<name_without_spaces>~~~~

Understanding the concept

The system consist of two very different languages:

• YAML makes it very easy to describe much content without using markup.
• HTML makes it very easy to describe almost no content with lots of markup.

However, it is possible to solve the weaknesses of these by mixing them up: a .yml.html file.

It is essentially a Html file, with yaml in a commented part, that can output to an .html file or be included in an other file.

The yaml will be parsed by the transformer, mixed with the included yaml files (first inclusion gets priority over the second, etc.), and then inputted into the mustache template (Mustache is a template format where you can insert maps, lists and other basic types). The mustache templates will be rerendered in a loop till the template does not include any more mustache tags (or a specified limit is reached) and is outputted by the transformer afterwards.

Mustache

This package relies on Mustache4Dart: https://pub.dartlang.org/packages/mustache4dart

The mustache specification can be found at: http://mustache.github.io/

Partials and other advanced features are not yet used in this package, but might be supported in a later version.

Usage warning

Warning: Transformers often have incompability issues:

Make sure that the yml2html transformer is listed above the dart_to_js_script_rewriter transformer:

transformers:
- yml2html
- dart_to_js_script_rewriter

The dart_to_js_script_rewriter leaves some artifacts in the builded html files, which results in getting a html, head and body tag at template usage:

Example file in the build directory:

<!DOCTYPE html><html lang="en"><head>
    <meta charset="UTF-8">
    <title>Test page</title>
</head>
<body>
Main Content title
<hr>
Main content text<br/>
<!-- the template content is messed up by the 'dart_to_js_script_rewriter' -->
<html><head></head><body><em>Hello World!</em></body></html>
<hr>
<script>alert("Test alert!");</script>

</body></html>

Advanced

This transformer renders the html files by iteratively rerendering a template to a specific depth, the default depth is 5.

The tranformer stops a render a soon as it can't find any more {{ in the rendered text to avoid unnecessary render cycles.

The depth is used to prevent infinite loops, which could consume lots of resources. A depth of 10 could be ok, but it shouldn't go deeper when working with large template files.

A custom depth could be defined with the depth setting in your pubspec.yaml:

transformers:
- yml2html:
    depth: 7

Installing

Example pubspec.yaml:

name: 'darttest'
version: 0.0.1
description: Dart test app

environment:
  sdk: '>=1.0.0 <2.0.0'

dependencies:
  yml2html: <version constraint>

transformers:
- yml2html:
    depth: 3
- dart_to_js_script_rewriter

Features and bugs

Please file feature requests and bugs at the issue tracker (at Github)

Some bugs are features, some features are bugs.

TODO

These are ideas for now, do not expect to see these features anytime soon.

1.0.0: AggregateTransformer -> Transformer

1.1.0: Included yml files should be able to include other yml files.

2.0.0: An alternative server to run the transformer on (instead of using pub serve)

3.0.0: Make the server extendable, maybe like a CMS?