Syntax

A Surfgreen site is mostly written in HTML and Markdown. But Surfgreen also includes a few features that make site development a little easier:

• Variables, which let you insert a piece of text based on the value of some metadata
• Blocks, to insert free-form HTML into another part of a page
• Conditionals, for only inserting content depending on the value of a particular variable
• Queries, to cycle through a series of pages and create a list out of them

Variables

Variables can be inserted into blocks by appending the name of a variable between two pairs of curly braces:

{{myVariable}}

You can specify variables in your page frontmatter (everything before the ~~~), like so:

title: My Page
category: Guitars

~~~

Here is my page

In this page, the variables {{title}} and {{category}} would be available to use in your blocks.

Built-in variables

Blocks

Blocks work like templates, allowing you to insert HTML into various parts of your site.

As we discussed, every Surfgreen site comes by default with three blocks: a header, body, and footer. These can be found as header.html, body.html, and footer.html. Blocks can contain other blocks, so you can create additional blocks that live inside these three "starter" blocks.

So, let's say you have a file in the blocks folder called my-block.html. You could add it to another Surfgreen block like so:

{{#my-block}}

Note the # after the curly braces: that lets Surfgreen know that this is a block, and not a variable.

Blocks can also contain variables. How does that work? Say you want to include a variable, color, in one of your blocks. You can set the value of color when you call the block:

{{#my-block color="red"}}

Then, you can reference that variable in your my-block block:

<div class="{{color}}">
    <p>The current color is {{color}}.</p>
</div>

Conditionals

Sometimes, you may only want to show certain content if a variable has a particular value. In Surfgreen, that's called a conditional.

Conditionals look a lot like blocks, with a # that comes first in a pair of curly braces. If you're familiar with programming languages, you'll get the general idea — but it's easy to learn if you haven't.

To continue our block example, let's say we want to only show a block if the color is a certain value. We would write:

{{#if color === "red"}}
This page is red!
{{/if}}

To continue it further, maybe we want to show something else if the page is not red. We can do that too:

{{#if color === "red"}}
This page is red!
{{#else}}
This page is not red.
{{/if}}

We can also conditionally show something if the page color does not equal red:

{{#if color !== "red"}}
This page is not red.
{{/if}}

Or, perhaps, we only want to show something if there's any color set:

{{#if color}}
This page has some sort of color.
{{/if}}

Queries

Occasionally, it's useful to get a collection of pages from your site, then list them out in a particular way. Maybe you want to create a mini sitemap that updates automatically, or a sidebar with links to pages in a particular category. In Surfgreen, that's called a query.

Queries look a lot like blocks and conditionals:

{{#query block="list-item"}}

This will grab all of your pages, and add them to a block called list-item.html. That block could include any variables for the page, like its title or URL.

That said, most of the time, we don't want to grab every page, just certain ones. In Surfgreen, a query block can look just for specific pages that have a particular variable in them.

So, if you only wanted to grab pages that have a color variable:

{{#query for="color" block="list-item"}}

Or pages that only have a color variable value of red:

{{#query for="color" value="red" block="list-item"}}

There are also arguments you can use to sort the pages in a query:

• sortby: The name of another variable that Surfgreen will use to sort.
• sort: Which direction to sort in — either asc for ascending or desc for descending.

Now, let's talk about how to work with assets like scripts or stylesheets in Surfgreen.