Zine

Site Structure

Main configuration file

A Zine website is defined by a zine.ziggy config file.

Here’s what the config of zine-ssg.io looks like:

zine.ziggy

Site {
   .title = "Zine - Static Site Generator",
   .host_url = "https://zine-ssg.io",
   .content_dir_path = "content",
   .layouts_dir_path = "layouts",
   .assets_dir_path = "assets",
   .static_assets = [
      // omitted for brevity
   ],
}

Once you put a zine.ziggy file in a directory, you’re able to run zine to start the dev server and begin edit your website.

File formats used by Zine

Zine uses SuperMD for content and SuperHTML for defining layouts.

Each file format has a dedicated page in the docs section.

The Content Directory

The content directory contains your SuperMD files and their structure will be reflected verbatim in the final site.

Note that SSGs rely heavily on the implication that webservers will automatically serve index.html when a directory (usually indicated by a final / in the URL) is requested.

Site Sections

Consider the following content structure:

content
├── about
│   └── contacts.smd
├── about.smd
├── blog
│   ├── a.smd
│   ├── b.smd
│   └── index.smd
└── index.smd

In Zine every index.smd file denotes a section.

The main use for sections is to group pages together for the purpose of defining content lists, like listing all posts in a blog section, for example.

In this example there are 2 sections:

The first one is the “root” section, defined by content/index.smd, containing:

The second section is the “blog” section, defined by content/blog/index.smd, containing:

Note how an index.smd file defines a section but as a page it is not included in the list of pages that belong to that same section.

Lastly, note how pages in a section don’t all share the same basepath. In the absence of a nested index.smd, all pages are considered siblings regardless of how deeply they are nested inside of different directories.

Frontmatter

Each SuperMD file must start with a Ziggy frontmatter delimited by --- (three dashes in a row).

Ziggy is a data serialization language similar to YAML and JSON. You can learn more on the official Ziggy website: https://ziggy-lang.io.

index.smd

---
.title = "Homepage",
.date = @date("2020-07-06T00:00:00"),
.author = "Sample Author",
.layout = "home.shtml",
.draft = false,
--- 
Your **SuperMD** content goes here.

Some fields, like title, and layout are mandatory, while others have default values. You can find a complete list of
frontmatter fields in the SuperMD documentation page.

A very important required field is layout. This field must point at the layout that you want to use to style your content. In Zine this field must always be explicitly filled out and there is no implicit naming convention (like in Hugo, for example).

The Layouts Directory

Layouts are used to style your content files. You can learn more about layouts in the SuperHTML Basics section.

The Assets Directory

This directory collects various assets (images, css files, etc) necessary to build the website. Note that unlike other mainstream static site generators, Zine doesn’t have a “static” asset folder as all assets are managed explicitly through Zine’s Asset System.

First Steps

The quickest way to start a Zine site is to run zine init, which will generate a sample site for you.

In this section we will instead go through the motions of bootstrapping a Zine website entirely from scratch.

First of all you need to create a zine.ziggy file and place it in an empty directory. The zine.ziggy file must be structured like the one at the top of this page.

Once that’s done, let’s create a home page and a relative template.

shell

$ touch content/index.smd
$ touch layouts/home.shtml

content/index.smd

---
.title = "Home",
.date = @date("2020-07-06T00:00:00"),
.author = "Sample Author",
.layout = "home.shtml",
.draft = false,
--- 
Hello World!

layouts/home.shtml

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title :text="$site.title"></title>
  </head>
  <body>
    <h1 :text="$page.title"></h1>
    <div :html="$page.content()"></div>
  </body>
</html>

public/index.shtml (output)

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Sample Site</title>
  </head>
  <body>
    <h1>Home</h1>
    <div><p>Hello World!</p></div>
  </body>
</html>

In this example we just saw:

If you start the dev server now by running zine, you should see the output page at http://localhost:1990/.

Adding more pages

Let’s imagine now that we want to add a blog section to our website with a first post in it.

shell

$ mkdir content/blog
$ touch content/blog/first-post.smd
$ touch layouts/post.shtml

content/blog/first-post.smd

---
.title = "First Post!",
.date = @date("2020-07-06T00:00:00"),
.author = "Sample Author",
.layout = "post.shtml",
.draft = false,
--- 
This is my first post!

layouts/post.shtml

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title :text="$site.title"></title>
  </head>
  <body>
    <h1>Blog</h1>
    <h2 :text="$page.title"></h2>
    <h3>by <span :text="$page.author"></span></h3>
    <h4>
      Posted on: 
      <span 
        :text="$page.date.format('January 02, 2006')"
      ></span>
    </h4>
    <div :html="$page.content()"></div>
  </body>
</html>

At this point you should be able to navigate to http://localhost:1990/blog/first-post/ and see the result.

Note how we needed a new layout (post.shtml) since the blog post is not going to have the same structure as the homepage.

While the structure is indeed different, both post.shtml and home.shtml share a lot of common boilerplate that can be collected into a single template by leveraging SuperHTML template extension features.

You can learn more about extending templates in the docs section dedicated to SuperHTML.

Multilingual sites

In this page we showed you the structure of a simple Zine website, but it’s also possible to use Zine to generate multilingual websites.

You can loarn more about that in the Multilingual (i18n) section.