To be able to use emerald, you need to have it available on your system. The easiest way to do that is to use the Nimble package manager:

$ nimble install emerald

Now using emerald consists of three simple steps:

1. Include emerald in your code.
2. Write templates
3. Call your templates

Sounds easy enough, doesn't it? Let's look at the details.

1. Import emerald

The emerald module exports everything you need to use emerald: The streams module from the standard library, and the emerald modules html and filters.

2. Write templates

You start writing a template with a proc header. The name of the proc is the name of your template. The template may take any number of parameters and may not have a return value. Then, you apply the macro html_templ to it. This macro is provided by emerald and will parse the body of the proc as html template.

In the body, every call that is a statement is interpreted as HTML tag. A call is a statement if it is not part of an expression, or put more simply: If it stands alone on its line. Calls may take two forms: Either a simple call (e.g. br()) or a call with a child block (e.g. head:). The example shows you how this looks in action.

You can use if, case and for loops inside templates. You can also define and use variables with var, let and const. Every expression that stands alone on a line and is not a call will be transformed to a string and written to the output HTML. By default, all string output will be filtered to escape special HTML characters (&, <, >).

emerald checks your HTML structure when parsing your templates. It may not be a fully replacement for the W3C HTML 5 validator, but it throws errors when you try to use HTML tags at places where they are forbidden, or if you forget to set required attributes. By the way, attributes can be set as named parameters, as you can see on the html element in the example. Instead of the string, you can use any expression to define the attribute's value. Some HTML attributes have names that are also keywords in Nim. When you set them, you need to use backticks around the name (e.g. `type`).

Be aware that while emerald allows you to embed quite much business logic in your template, you shouldn't embed program logic in the template unless it's absolutely necessary. Other templating engines like e.g. mustache forbid you by design to embed any logic in the template, because the template is not the place for it. emerald allows it because it doesn't want to stand in your way, so it's up to you to use its features with care.

As any standalone call will create an HTML tag, emerald provides a special syntax to actually call procs: Use the familiar discard command to call a proc without using its return value, and the emerald-specific put command to output the return value of a call.

If you have a snippet which you want to use multiple times, or if you want to just separate a piece of your template from the rest, you can use mixins. Mixins are snippets you can include multiple times in your template. Like the template itself, mixins can take any number of parameters. Mixins are even able to take block content as input, which can be called from inside the mixin by using the special call mixin_content(). In the template, you can call the mixin with the command call_mixin. Look at the example to see how this works.

There is no syntax to call another template from within a template, because this is not considered a use-case that makes sense. But you can call mixins from within mixins.

3. Call your templates

While you write your template as proc, it isn't a proc anymore after emerald has parsed it. Instead, it is an object type. You can create a new instance with newName(). This proc never takes parameters. The parameters you declared for the template are settable as object values. You can render the template by calling the object's render proc. This proc takes a Stream as second parameter after the template instance. When calling render, the template will be rendered into the given stream.

This concludes the tutorial. For a more detailed documentation of emerald's features, refer to the documentation section.