i haza website

Templates & page design

I Haza Website uses a Liquid templating engine to give you full control over how a published website looks and is structured. Work with your existing project's style sheets and partials all synchronised across all your devices.

Preview mode from the editor toolbar uses the same rendering pipeline as publishing, so you can see exactly how the current page will look with the click of a button.

Templates

A template can be added to a project by selecting New File on the project or a folder. Give the new file a .liquid extension to create the file as a template, the first template created is used as the default for rendering your content.

See File extensions for the full set of file types available. A template shows a distinct icon in the sidebar so it's easy to tell apart from ordinary pages. Templates are files containing HTML and Liquid syntax. You write markup directly, using source mode in the editor which has syntax highlighting applied. The only options you will see in the editor toolbar are undo and redo. Template content is auto saved and synchronised between devices like all other content.

The first template you create in a project automatically becomes its default. This is the template that Preview and Publish both use. Once a project has more than one template in a folder, a ✓ Set Default action is then shown in the ⋯ actions menu of each template. The current default shows a small check mark next to its name.

Previewing a page

Open any content page and click Preview in the toolbar. This renders the page through the file's selected template and shows the result in a full-screen overlay. This is the same rendering that is used when you publish, so you can see exactly how it will be displayed. A couple of notes:

Preview reflects whatever is currently on screen, including any edit you just made. Make sure you still click Publish when you're ready!
The browser's back button also closes the preview, along with the close button in the top right corner.
Preview isn't available on CSS files or a template itself (they have no rendered content of their own to preview) - but it's available while viewing a page's HTML via View source.
If a project has no template yet, Preview still works - it just shows the page's own rendered HTML.

Warnings

If anything in the template couldn't be resolved cleanly then the preview will still open, but a warnings dialog will be shown as well. This will name the template and list what needs to be fixed.

Warnings are re-checked each time you click preview to check if you've fixed the template. The same checks run again when you publish, so anything left unresolved shows up there too.

Template syntax

I Haza Website supports standard Liquid syntax, see the Liquid documentation for an introduction to what's available. A template written in core Liquid syntax should import with minimal changes.

If you're importing templates used with other generators such as Shopify or Jekyll, then please read on as many of their platform specific tags are not available.

On top of standard Liquid syntax, a few reserved variables and tags are always available in every template.

Page content

This is the most important tag to be aware of, as it refers to the full content of your rich text pages. It's standard Liquid variable syntax, but content is specifically reserved for the rendered HTML of the page currently being previewed or published. This is the one definition that every template needs somewhere in its markup. If it's missing, you'll be warned that the page won't appear at all.

The simplest template you will want to create is:

<html>
  <body>
    {{ content }}
  </body>
</html>

Page info

Here page is another reserved variable, with properties supplied to your templates from the page being rendered:

page.title - the first heading in the page content, or its file name if no heading is found.
page.name - the page's file name.
page.url - the page's own address on the published site, such as /posts/hello.html.

<title>{{ page.title }}</title>

A page in a posts folder also has:

page.published - the date and time it was published, usable with Liquid's own date filter. Empty for a draft that hasn't been given a date yet.
page.draft - true while the post is a draft.
page.previous and page.next - the older and newer published posts in the same posts folder, each with its own url, title, name, published and content. Empty for the oldest and newest posts, and for drafts.

<time>{{ page.published | date: "%-d %B %Y" }}</time>
{% if page.previous %}<a href="{{ page.previous.url }}">{{ page.previous.title }}</a>{% endif %}
{% if page.next %}<a href="{{ page.next.url }}">{{ page.next.title }}</a>{% endif %}

Referencing files

The {% file %} tag references another file in the project or your media library by name. It can include paths through folders, like "images/logo.png". How it's applied depends on what's it's referencing:

A .css file becomes a URL, meant to go inside your own <link> tag:
```
<link rel="stylesheet" href="{% file "styles.css" %}">
```
Note that not including rel="stylesheet" on a css file means the browser silently ignores the link entirely, so this will generate a warning.

An image (from your media library) also becomes a URL:

<link rel="icon" href="{% file "favicon.png" %}">
<img src="{% file "photo.jpg" %}">

Any other page has its own rendered content included directly in place, as if you'd pasted it there:
```
<header>{% file "site-header.html" %}</header>
```

If your file tag doesn't match an existing file then it will be stripped out and a warning will be shown.

Reusable partials

Partials reference other templates and include them when rendering. This allows for shared partials, like a footer or navigation block that can be used by more than one template. Unlike {% file %}, the referenced template's own Liquid gets evaluated, so a partial can use variables and logic of its own. In this example the page variable mentioned above is passed down:

{% render "footer.liquid", page: page %}

Liquid's own standard tags {% include %} and {% layout %} are also available, but render is the best to use by default as it doesn't leak the calling template's own variables into the partial the way include does.

Local variables

There's no separate settings file - a template just assigns its own variables at the top, using Liquid's own {% assign %}:

{% assign favicon = "favicon.png" %}
<link rel="icon" href="{% file favicon %}" />

Site info

site is another reserved variable, for project-wide information rather than anything specific to the page currently being rendered:

site.title - the project's own name.
site.url - the project's published URL, for example https://myproject.haza.website. Combine it with {% file %} when you need an absolute URL instead of the relative one: {{ site.url }}{% file "styles.css" %}. This is useful for a page that might end up being displayed somewhere other than its own published site.
site.time - the date and time of the current render, usable with Liquid's own date filter:

<title>{{ site.title }}</title>
<link rel="canonical" href="{{ site.url }}" />
<footer>&copy; {{ site.time | date: "%Y" }} {{ site.title }}</footer>

site.feeds - each posts folder's RSS feed, keyed by the folder's path in the project (such as blog, or writing/blog for a posts folder inside another folder), with its own url and title. The title is the project's name, followed by the folder's name when the folder's name is included in URLs. Publishing writes a feed for each posts folder that has published posts, with the newest 20 posts in full, once the project has a domain, and site.feeds lists them from then on. Add a link to it in your template's <head> so feed readers can find it from your site's address:

<link rel="alternate" type="application/rss+xml" title="{{ site.feeds.blog.title }}" href="{{ site.feeds.blog.url }}" />

site.posts - each posts folder's published posts, newest first, keyed by the folder's path like site.feeds. Each post has its url, title, name, published and its full content. Use it in a separate template for your home page, and pick how many posts to show with limit:

{% for post in site.posts.blog limit:5 %}
<article>
  {{ post.content }}
  <a href="{{ post.url }}">{{ post.published | date: "%-d %B %Y" }}</a>
</article>
{% endfor %}

To page through all your posts instead, use a pager.

A template can make its own pages of posts, with no page required in your project to apply it to. Add a pager to front matter at the top of the template, between --- lines:

---
pager:
  size: 5
  format: page-{n}
  index: true
---
{% for post in pager.posts %}
<article>{{ post.content }}</article>
{% endfor %}
{% if pager.previous %}<a href="{{ pager.previous }}">Older posts</a>{% endif %}
{% if pager.next %}<a href="{{ pager.next }}">Newer posts</a>{% endif %}

This publishes one page for every 5 posts next to the template, named index.html, page-2.html, page-3.html and so on, and adds another page as you publish more posts. Preview, Export and Publish all include them.

size - how many posts each page shows. Defaults to 10 when not provided.
format - the name of each page, with {n} for its number. Defaults to page-{n} when not provided.
index - true makes the first page index.html, this is your site's home page when the template is at the top level. Without it the first page is page-1.html when using the default format.
posts - which posts folder to list, by its path. Only needed when your project has more than one.

The template gets pager.posts with this page's posts, pager.number and pager.total, and pager.previous and pager.next with the URLs of the older and newer pages, the same as a post's page.previous and page.next values. They're empty on the last and first pages. A page you write yourself with the same name is published instead of the generated one.

Code highlighting theme

A URL for the project's chosen code-highlighting theme. Add it to a template the same was you reference other css files:

<link rel="stylesheet" href="{{ site.codeThemeLight }}" />
<link
  rel="stylesheet"
  href="{{ site.codeThemeDark }}"
  media="(prefers-color-scheme: dark)"
/>

This example switches the theme based on the user's preference for light or dark mode, however you can simplify to one or the other themes if you prefer. If a project has no templates then both style sheets are published when any of your pages contain code blocks, so that they automatically use your chosen syntax highlighting.

Plugins

Adds one of a small set of built-in interactive behaviors, such as a lightbox for images, a light and dark mode toggle, or copy buttons on code blocks:

{% plugin "lightbox" %}

See Plugins for every plugin and the variables each one takes.

Style sheets

Create a CSS file by clicking New File and then naming the file with a .css extension. The editor will then automatically apply CSS syntax highlighting.

Fonts

A font is added to your media library and shared across projects. You can then reference it in a template the same way you reference other files:

<style>
  @font-face {
    font-family: "My Font";
    src: url("{% file "MyFont.woff2" %}") format("woff2");
  }
  body {
    font-family: "My Font", sans-serif;
  }
</style>

Only the @font-face rule itself needs to be in the template - once it's declared there, the font is registered for the whole site, so any other style sheet can use font-family: "My Font" without a reference path of its own.

Worked example

A minimal but complete template, with a stylesheet, a favicon, a per-page title alongside the site's own, and highlighted code blocks:

{% assign favicon = "favicon.png" %}
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>{{ page.title }} - {{ site.title }}</title>
  <link rel="icon" href="{% file favicon %}">
  <link rel="stylesheet" href="{% file "styles.css" %}">
  <link rel="stylesheet" href="{{ site.codeThemeLight }}">
  <link rel="stylesheet" href="{{ site.codeThemeDark }}" media="(prefers-color-scheme: dark)">
</head>
<body>
  <header>{% file "site-header.html" %}</header>
  <main>{{ content }}</main>
</body>
</html>