Front Matter

Front matter is a block you can place at the top of your template files to give EJS Site Builder extra details about how to generate html files.

Front matter is designed to be human readable at a glance, but is also parsed by EJS Site Builder, so it must follow specific rules. EJS Site Builder's front matter must be written in YAML, which is self described as "a human-friendly data serialization language for all programming languages."

Variables For Rendering

Front matter can be used as data when rendering your template. EJS Site Builder uses EJS templating so that you can do everything in javascript without dealing with other templating languages. To use a front matter variable in your EJS template, you'd do something like this:

---
title: hello world
---

The title of this page is <%= title %>

In the above example, at generation time, the title from front matter will be used to replace the EJS title tag.

With YAML and javascript, the sky is the limit.

For example, You can also pass variables to sub templates that you include. YAML also allows for structured data like arrays which you could then iterate through using EJS. Below is an example which takes a list of fruits from front matter, loops over them using javascript forEach, and includes sub-templates that you also write using EJS functionality:

index.ejs:

---
fruits: [orange, apple, grape, pear]
---

<ul>
  <% fruits.forEach(function(fruit){ %> <%- include('fruitTemplate', {name:
  fruit}); %> <% }); %>
</ul>

fruitTemplate.ejs:

Fruit: <%= name %>

Note 1: that front matter in your templates is optional, though it's likely good practice to specify things like title, description, and path, and tags if you are making a blog etc, so that you can summarize your content.

Note 2: As long as you don't use a reserved name, you can pass any data to your templates using front matter variables. Variables that you specify can also be accessed from your generate scripts.

Reserved Variables that control EJS Site Builder's behaviour

EJS Site Builder assigns special meaning to several variables which you can use to configure your template's output:

Generate

---
generate: <path>
---

Generate tells ejssitebuilder that a template is going to directly generate one or more html pages.

<path> is the relative path off the root of your site where the corresponding output index.html file will be generated. If a generate script is specified in your template, the path can be used with a wildcard to indicate the base path for multiple output files.

Templates can either be sub templates, or compontents of other templates (when you want to break a large template into reusable components), or they can trigger the generation of one or more pages with this front matter variable. If you are specifying a script without any ejs template data that you plan to re-use in other templates, leave genreate blank:

input-folder/generators/myScript.ejs

---
generate:
---

<script generate>
  // some reuseable code
</script>

And then in the template you want to include the script from:

<script generate-use:"generators/myScript">
</script>

Wrapper

Sometimes you want to re-use the header and footer parts of an html page, for example to set up site analytics, meta data, etc. Specifying a wrapper will use the wrapper template to wrap the content generated by your template, as long as the wrapper template as a special include called "_body", which tells it where to insert your wrapped content. See an example here.

---
wrapper: <template name>
---

Reserved Variables passed to your templates automatically.

See calculated page variables for details.