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 link
ing it:
$site.asset('logo.png').link()
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
A.png
belongs tocontent/index.smd
B.png
belongs tocontent/blog/index.smd
C.png
belongs tocontent/blog/first-post.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 link
ed 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 link
ed to be installed in the output directory.
See the doc comments for zine.BuildAsset
for more info.
Next Steps
Read the SuperMD Basics page to learn more about asset-related syntax in SuperMD.
Read the SuperHTML Scripty reference page page to know what operations are available for assets and other kinds of data in SuperHTML. The Assets section might be of particular interest.