Zine
SuperHTML Scripty Reference
Global Scope
$site
: Site
The current website. In a multilingual website, each locale will have its own separate instance of $site
$page
: Page
The page being currently rendered.
$build
: Build
Gives you access to build-time assets (i.e. assets built via the Zig build system) alongside other information relative to the current build.
$i18n
: Map
In a multilingual website it contains the translations defined in the corresponding i18n file.
See the i18n docs for more info.
$ctx
: Ctx
A key-value mapping that contains data defined in <ctx>
nodes.
$loop
: ?Iterator
The current iterator, only available within elements that have a loop
attribute.
$if
: ?any
The current branching variable, only available within elements that have an if
attribute used to unwrap an optional value.
Site
The global site configuration. The fields come from the call to website
in your build.zig
.
Gives you also access to assets and static assets from the directories defined in your site configuration.
Fields
host_url
: String
The host URL, as defined in your build.zig
.
title
: String
The website title, as defined in your build.zig
.
Functions
fn
localeCode () -> String
In a multilingual website, returns the locale of the current variant as defined in your build.zig
file.
Examples
<html lang="$site.localeCode()"></html>
fn
localeName () -> String
In a multilingual website, returns the locale name of the current variant as defined in your build.zig
file.
Examples
<span text="$site.localeName()"></span>
fn
link () -> String
Returns a link to the homepage of the website.
Correctly links to a subpath when correct to do so in a
multilingual website.
Examples
<a href="$site.link()" text="$site.title"></a>
fn
asset (String) -> Asset
Retuns an asset by name from inside the assets directory.
Examples
<img src="$site.asset('foo.png').link()">
fn
page (String) -> Page
Finds a page by path.
Paths are relative to the content directory and should exclude the markdown suffix as Zine will automatically infer which file naming convention is used by the target page.
For example, the value 'foo/bar' will be automatically matched by Zine with either:
- content/foo/bar.smd
- content/foo/bar/index.smd
Examples
<a href="$site.page('downloads').link()">Downloads</a>
fn
pages (String, [String...]) -> [Page]
Same as page
, but accepts a variable number of page references and loops over them in the provided order. All pages must exist.
To be used in conjunction with a loop
attribute.
Examples
<ul loop="$site.pages('a', 'b', 'c')"><li text="$loop.it.title"></li></ul>
fn
locale (String) -> Site
Returns the Site corresponding to the provided locale code.
Only available in multilingual websites.
Examples
<a href="$site.locale('en-US').link()">Murica</a>
Page
The page currently being rendered.
Fields
title
: String
Title of the page, as set in the SuperMD frontmatter.
description
: String
Description of the page, as set in the SuperMD frontmatter.
author
: String
Author of the page, as set in the SuperMD frontmatter.
date
: Date
Publication date of the page, as set in the SuperMD frontmatter.
Used to provide default ordering of pages.
layout
: String
SuperHTML layout used to render the page, as set in the SuperMD frontmatter.
draft
: Bool
When set to true the page will not be rendered in release mode, as set in the SuperMD frontmatter.
tags
: [String]
Tags associated with the page, as set in the SuperMD frontmatter.
aliases
: [String]
Aliases of the current page, as set in the SuperMD frontmatter.
Aliases can be used to make the same page available from different locations.
Every entry in the list is an output location where the rendered page will be copied to.
alternatives
: [Alternative]
Alternative versions of the page, as set in the SuperMD frontmatter.
Alternatives are a good way of implementing RSS feeds, for example.
skip_subdirs
: Bool
Skips any other potential content present in the subdir of the page, as set in the SuperMD frontmatter.
Can only be set to true on section pages (i.e. index.smd
pages).
translation_key
: ?String
Translation key used to map this page with corresponding localized variants, as set in the SuperMD frontmatter.
See the docs on i18n for more info.
custom
: any
A Ziggy map where you can define custom properties for the page, as set in the SuperMD frontmatter.
Functions
fn
isCurrent () -> Bool
Returns true if the target page is the one currently being rendered.
To be used in conjunction with the various functions that give you references to other pages, like $site.page()
, for example.
Examples
<div class="$site.page('foo').isCurrent().then('selected')"></div>
fn
asset (String) -> Asset
Retuns an asset by name from inside the page's asset directory.
Assets for a non-section page must be placed under a subdirectory that shares the same name with the corresponding markdown file.
(as a reminder sections are defined by pages named index.smd
)
section? | page path | asset directory |
---|---|---|
yes | blog/foo/index.smd | blog/foo/ |
no | blog/bar.smd | blog/bar/ |
Examples
<img src="$page.asset('foo.png').link(false)">
fn
site () -> Site
Returns the Site that the page belongs to.
Examples
<div :text="$page.site().localeName()"></div>
fn
locale (String) -> ?Page
Returns a reference to a localized variant of the target page.
Examples
<div text="$page.locale('en-US').title"></div>
fn
locale? (String) -> ?Page
Returns a reference to a localized variant of the target page, if present. Returns null otherwise.
To be used in conjunction with an if
attribute.
Examples
<div :if="$page.locale?('en-US')">
<a href="$if.link()" :text="$if.title"></a>
</div>
fn
locales () -> [Page]
Returns the list of localized variants of the current page.
Examples
<div loop="$page.locales()"><a href="$loop.it.link()" text="$loop.it.title"></a></div>
fn
wordCount () -> Int
Returns the word count of the page.
The count is performed assuming 5-letter words, so it actually counts all characters and divides the result by 5.
Examples
<div :loop="$page.wordCount()"></div>
fn
parentSection () -> Page
Returns the parent section of a page.
It's always an error to call this function on the site's main index page as it doesn't have a parent section.
Examples
$page.parentSection()
fn
isSection () -> Bool
Returns true if the current page defines a section (i.e. if the current page is an 'index.smd' page).
Examples
$page.isSection()
fn
subpages () -> [Page]
Returns a list of all the pages in this section. If the page is not a section, returns an empty list.
Sections are defined by index.smd
files, see the content structure section in the official docs for more info.
Examples
<div :loop="$page.subpages()">
<span :text="$loop.it.title"></span>
</div>
fn
nextPage () -> ?Page
Returns the next page in the same section, sorted by date.
The returned value is an optional to be used in conjunction with an if
attribute. Use $if
to access the unpacked value within the if
block.
Examples
<div :if="$page.nextPage()">
<span :text="$if.title"></span>
</div>
fn
prevPage () -> ?Page
Tries to return the page before the target one (sorted by date), to be used with an if
attribute.
Examples
<div if="$page.prevPage()"></div>
fn
hasNext () -> Bool
Returns true of the target page has another page after (sorted by date)
Examples
$page.hasNext()
fn
hasPrev () -> Bool
Returns true of the target page has another page before (sorted by date)
Examples
$page.hasPrev()
fn
link () -> String
Returns the URL of the target page.
Examples
$page.link()
fn
permalink () -> String
Deprecated, use link()
Examples
fn
content () -> String
Renders the full Markdown page to HTML
Examples
fn
contentSection (String) -> String
Renders the specified content section of a page.
Examples
<div :html="$page.contentSection('section-id')"></div>
<div :html="$page.contentSection('other-section')"></div>
fn
contentSections () -> [ContentSection]
Returns a list of sections for the current page.
A page that doesn't define any section will have a default section for the whole document with a null id.
Examples
<div :html="$page.contentSections()"></div>
fn
toc () -> String
Renders the table of content.
Examples
<div html="$page.toc()"></div>
Ctx
A special map that contains all the attributes defined on <ctx>
in the current scope.
You can access the available fields using dot notation.
Example:
<div>
<ctx foo="(scripty expr)" bar="(scripty expr)">
<span :text="$ctx.foo"></span>
<span :text="$ctx.bar"></span>
</ctx>
</div>
Alternative
An alternative version of the current page. Title and type can be used when generating <link rel="alternate">
elements.
Fields
name
: String
A name that can be used to fetch this alternative version of the page.
layout
: String
The SuperHTML layout to use to generate this alternative version of the page.
output
: String
Output path where to to put the generated alternative.
type
: String
A metadata field that can be used to set the content-type of this alternative version of the Page.
Useful for example to generate RSS links:
<ctx alt="$page.alternative('rss')"
<a href="$ctx.alt.link()"
type="$ctx.alt.type"
text="$ctx.alt.name"
></a>
</ctx>
ContentSection
A content section from a page.
Fields
id
: String
The id of the current section.
data
: Map
A Ziggy Map that contains data key-value pairs set in SuperMD
Functions
fn
heading () -> String
If the section starts with a heading element, this function returns the heading as simple text.
Examples
<div html="$loop.it.heading()"></div>
fn
heading? () -> ?String
If the section starts with a heading element, this function returns the heading as simple text.
Examples
<div html="$loop.it.heading()"></div>
fn
html () -> String
Renders the section.
Examples
<div html="$loop.it.html()"></div>
Build
Gives you access to build-time assets and other build related info.
Fields
generated
: Date
Returns the current date when the build is taking place.
Note
Using this function will not add a dependency on the current time for the page, hence the name generated
.
To get the best results, use in conjunction with caching as otherwise the page will be regenerated anew every single time.
Functions
fn
asset (String) -> Asset
Retuns a build-time asset (i.e. an asset generated through your 'build.zig' file) by name.
Examples
<div text="$build.asset('foo').bytes()"></div>
Asset
Represents an asset.
Functions
fn
link () -> String
Returns a link to the asset.
Calling link
on an asset will cause it to be installed under the same relative path into the output directory.
`content/post/bar.jpg` -> `zig-out/post/bar.jpg`
assets/foo/bar/baz.jpg
-> zig-out/foo/bar/baz.jpg
Build assets will be installed under the path defined in your build.zig
.
Examples
<img src="$site.asset('logo.jpg').link()">
<img src="$page.asset('profile.jpg').link()">
fn
size () -> String
Returns the size of an asset file in bytes.
Examples
<div text="$site.asset('foo.json').size()"></div>
fn
bytes () -> String
Returns the raw contents of an asset.
Examples
<div text="$page.assets.file('foo.json').bytes()"></div>
fn
ziggy () -> any
Tries to parse the asset as a Ziggy document.
Examples
<div text="$page.assets.file('foo.ziggy').ziggy().get('bar')"></div>
Map
A map that can hold any value, used to represent the custom
field in Page frontmatters or Ziggy / JSON data loaded from assets.
Functions
fn
getOr (String, String) -> String
Tries to get a value from a map, returns the second value on failure.
Examples
$page.custom.getOr('coauthor', 'Loris Cro')
fn
get (String) -> any
Tries to get a value from a map, errors out if the value is not present.
Examples
$page.custom.get('coauthor')
fn
get? (String) -> ?any
Tries to get a dynamic value, to be used in conjuction with an if
attribute.
Examples
<div if="$page.custom.get?('myValue')">
<span text="$if"></span>
</div>
fn
has (String) -> Bool
Returns true if the map contains the provided key.
Examples
<div if="$page.custom.has('myValue')">Yep!</div>
fn
iterate () -> [KV]
Iterates over key-value pairs of a Ziggy map.
Examples
$page.custom.iterate()
fn
iterPattern (String) -> [KV]
Iterates over key-value pairs of a Ziggy map where the key matches the given pattern.
Examples
$page.custom.iterPattern("user-")
?any
An optional value, to be used in conjunction with if
attributes.
String
A string.
Functions
fn
len () -> Int
Returns the length of a string.
Examples
$page.title.len()
fn
contains (String) -> Bool
Returns true if the receiver contains the provided string.
Examples
$page.permalink().contains("/blog/")
fn
endsWith (String) -> Bool
Returns true if the receiver ends with the provided string.
Examples
$page.permalink().endsWith("/blog/")
fn
eql (String) -> Bool
Returns true if the receiver equals the provided string.
Examples
$page.author.eql("Loris Cro")
fn
basename () -> String
Returns the last component of a path.
Examples
TODO
fn
suffix (String, [String...]) -> String
Concatenates strings together (left-to-right).
Examples
$page.title.suffix("Foo","Bar", "Baz")
fn
prefix (String, [String...]) -> String
Concatenates strings together (left-to-right) and prepends them to the receiver string.
Examples
$page.title.prefix("Foo","Bar", "Baz")
fn
fmt (String, [String...]) -> String
Looks for '{}' placeholders in the receiver string and replaces them with the provided arguments.
Examples
$i18n.get!("welcome-message").fmt($page.custom.get!("name"))
fn
addPath (String, [String...]) -> String
Joins URL path segments automatically adding /
as needed.
Examples
$site.host_url.addPath("rss.xml")
$site.host_url.addPath("foo/bar", "/baz")
fn
syntaxHighlight (String) -> String
Applies syntax highlighting to a string. The argument specifies the language name.
Examples
<pre>
<code class="ziggy"
html="$page.custom.get('sample').syntaxHighLight('ziggy')"
></code>
</pre>
fn
parseInt () -> Int
Parses an integer out of a string
Examples
$page.custom.get!('not-a-num-for-some-reason').parseInt()
fn
parseDate () -> Date
Parses a Date out of a string.
Examples
$page.custom.get('foo').parseDate()
fn
splitN (String, Int) -> String
Splits the string using the first string argument as delimiter and then returns the Nth substring (where N is the second argument).
Indices start from 0.
Examples
$page.author.splitN(" ", 1)
fn
lower () -> String
Returns a lowercase version of the target string.
Examples
$page.title.lower()
Date
A datetime.
Functions
fn
gt (Date) -> Bool
Return true if lhs is later than rhs (the argument).
Examples
$page.date.gt($page.custom.expiry_date)
fn
lt (Date) -> Bool
Return true if lhs is earlier than rhs (the argument).
Examples
$page.date.lt($page.custom.expiry_date)
fn
eq (Date) -> Bool
Return true if lhs is the same instant as the rhs (the argument).
Examples
$page.date.eq($page.custom.expiry_date)
fn
format (String) -> String
Formats a datetime according to the specified format string.
Zine uses Go-style format strings, which are all variations based on a "magic date":
Mon Jan 2 15:04:05 MST 2006
By tweaking its components you can specify various formatting styles.
Examples
$page.date.format("January 02, 2006")
$page.date.format("06-Jan-02")
$page.date.format("2006/01/02")
$page.date.format("2006/01/02 15:04 MST")
fn
formatHTTP () -> String
Formats a datetime according to the HTTP spec.
Examples
$page.date.formatHTTP()
Bool
A boolean value
Functions
fn
then (String, ?String) -> String
If the boolean is true
, returns the first argument. Otherwise, returns the second argument.
The second argument defaults to an empty string.
Examples
$page.draft.then("<alert>DRAFT!</alert>")
fn
not () -> Bool
Negates a boolean value.
Examples
$page.draft.not()
fn
and (Bool, [Bool...]) -> Bool
Computes logical and
between the receiver value and any other value passed as argument.
Examples
$page.draft.and($site.tags.len().eq(10))
fn
or (Bool, [Bool...]) -> Bool
Computes logical or
between the receiver value and any other value passed as argument.
Examples
$page.draft.or($site.tags.len().eq(0))
Int
A signed 64-bit integer.
Functions
fn
eq (Int) -> Bool
Tests if two integers have the same value.
Examples
$page.wordCount().eq(200)
fn
gt (Int) -> Bool
Returns true if lhs is greater than rhs (the argument).
Examples
$page.wordCount().gt(200)
fn
plus (Int) -> Int
Sums two integers.
Examples
$page.wordCount().plus(10)
fn
div (Int) -> Int
Divides the receiver by the argument.
Examples
$page.wordCount().div(10)
fn
byteSize () -> String
Turns a raw number of bytes into a human readable string that appropriately uses Kilo, Mega, Giga, etc.
Examples
$page.asset('photo.jpg').size().byteSize()
Float
A 64bit float value.
Iterator
An iterator.
Fields
it
: any
The current iteration variable.
idx
: Int
The current iteration index.
first
: Bool
True on the first iteration loop.
last
: Bool
True on the last iteration loop.
len
: Int
The length of the sequence being iterated.
Functions
fn
up () -> Iterator
In nested loops, accesses the upper $loop
Examples
$loop.up().it
err
A Scripty error.
In Scripty all errors are unrecoverable. When available, you can use ?
variants of functions (e.g. get?
) to obtain a null value instead of an error.