Zine

Assets

Assets in Zine

A Zine site can have 3 kinds of assets: site, page, and build assets.

Note

SuperMD and SuperHTML have different ways of accessing assets, make sure to read their respective documentation pages first.

Site Assets

These assets are located under assets_dir_path.

In SuperHTML, the main way of accessing site assets is by accessing them through an instance of Site: $site.asset('logo.png').

Once you have an Asset, the main way to use it is by linking it:

Calling link on an asset will cause Zine to install it in the output directory. Conversely, accessing an asset without calling link on it will not cause it to be installed.

SuperMD

In SuperMD you can reference assets using the appropriate functions of $link, $image or $video. Referencing an asset in SuperMD will cause it to be installed just like it does for SuperHTML.

The SuperHTML Scripty reference page lists all other operations that can be performed on instances of Asset.

One example of where this makes sense is when you have a Ziggy (or JSON) document that you want to use to build a page, but that is not meant to be included the final output.

songs-list.shtml

<ul :loop="$page.asset('songs.json').ziggy()">
  <li :text="$loop.it.get('name')"></li>
</ul>

NOTE

Zine uses Ziggy as its data serialization format of choice, but JSON documents happen to be a valid subset of Ziggy, so you can use them directly.

Static Site Assets

Some assets should be installed even if no layout or page refers to them.

For example favicon.ico might not be referenced, but browsers will automatically try to fetch it.

Another example could be .well-known assets or files that might have special meaning for the hosting service that you're using.

For example, GitHub uses a file named CNAME to keep track of the custom domain configured for a given GitHub Pages website.

One last example would be font files only referenced inside of CSS files, as Zine currently lacks the ability to inspect CSS files.

To install assets unconditionally, list them in static_assets in your build.zig:

build.zig

pub fn build(b: *std.Build) !void {
    zine.website(b, .{
        .title = "Zine - Static Site Generator",
        .host_url = "https://zine-ssg.io",
        .layouts_dir_path = "layouts",
        .content_dir_path = "content",
        .assets_dir_path = "assets",
        .static_assets = &.{
            // Used by GitHub Pages
            "CNAME",
            // This asset is referenced in some inlined HTML in Markdown
            // which Zine is not yet able to analyze so as a temporary
            // hack we mark it as a static asset.
            "vscode-autoformatting.mp4",

            // Font referenced in CSS files
            "BebasNeue-Regular.ttf",
        },
    });
}

Page Assets

Page assets are the same as site assets, but are located inside of content_dir_path, next to the page that references them.

If you have an asset that is specific to only a single page of your website, you can conveniently place it next to it inside the content directory, but beware of respecting the expected content structure.

shell

content
├── blog
│   ├── first-post.smd
│   └── index.smd
└── index.smd

In Zine, pages that are not named index.smd (i.e. pages that don't define a section) must keep their assets under a directory with the same name.

shell

content
├── blog
│   ├── first-post
│   │   └── C.png
│   ├── first-post.smd
│   ├── B.png
│   └── index.smd
├── A.png
└── index.smd

Note how C.png lives under content/blog/first-post/ because it belongs to a non-section page.

Accessing a page asset in SuperHTML can be done using $page.asset('C.png'). Like all assets, they must be linked to be installed in the output directory.

Build Assets

If you have artifacts built using the Zig build system, you can use them in Zine by setting build_assets in your build.zig.

Accessing a build asset in SuperHTML can be done using $build.asset('foo'). Like all assets, they must be linked to be installed in the output directory.

See the doc comments for zine.BuildAsset for more info.

Next Steps