Templates

Highlighting Static Content

Templates

Mendoza has a simple templating system for easily wrapping your content in boilerplate HTML tags. Templates are the easiest way to customize the structure of your website. Templates live in the templates/ directory of your site source.

Using templates

To use a template, you need to add the :template key to the front-matter of your markup file. You can place your own templates in the templates/ directory of your project, and then reference them by their path. 

{:title "My Blog Post"
 :template "my-template.html"}
---
Hello, blog!

A Simple Template

The simplest template is just a plain HTML file. 

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

Code in Templates

The main benefit of templates is the ability to embed both Janet code and other templates inside ypur pages. The template syntax has three ways to include Janet expressions in the generated html (or any other kind of text file!). The body of your content markup will be exposed in the template as the content binding.

{{ node }}

Use of double curly braces in a template substitutes a node of the document graph in the final output. node must be a Janet expression that will be rendered and spliced into the output file. node will usually be either a string or a nested table, representing a DOM node that will be rendered by mendoza/render. You can also include other templates with the :template key in the node. 

<!doctype html>
<html>
  <head>
    {{ {:template "mytemplate/head.html"} }}
  </head>
  <body>
    {{ content }}
  </body>
  <footer>
    {{ {:template "mytemplate/footer.html} }}
  </footer>
</html>

{% raw-janet %}

It is often useful to be able to create loops or other logic inside a template to generate lists, tables, and other data. This syntax lets you splice Janet code into the template, so is very powerful when paired with Janet's looping constructs like for, each, loop, and while. Code inside these delimiters will be executed every time the template runs. 

<!doctype html>
<html>
  <body>
    <ul>
      {% (for i 0 100 %}
        <li>Item {{ i }}</li>
      {% ) %}
    </ul>
  </body>
</html>

When inserting HTML inside janet forms like above, the HTML will be appended to the final output each time the body of that form is run. This means that although the for macro in Janet evaluates to nil, 100 items will still be added to output document.

{$ janet $}

Dollar braces are similar to percent braces, but will only run once, when the template is compiled. You can use the delimiters to import Janet modules or define helper functions for your template. The results of items here will not be included in the output html. 

{$ (import json) $}
<!doctype html>
<html>
  <body>
      <pre>
        {{ (janet/encode (range 100)) }}
      </pre>
  </body>
</html>

State from the front-matter

Almost all templates will want to use parameters passed down from the content file, such as a title, author, description, post date, etc. Such data can be added to the front-matter of the .mdz files, and the templates can pick it up via dynamic bindings in the template. 

<!doctype html>
<html>
  <head>
    <title>{{ (dyn :title) }}</title>
  </head>
  <body>
    {{ content }}
  </body>
  <footer>
    Copyright &copy; {{ (dyn :author) }} 2019
  </footer>
</html>

Built in templates

Mendoza comes with a few built in templates. They should work well on their own or serve as good starting points for your own templates.

Highlighting Static Content