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>

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] (see also [any])

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] (see also [any])

Tags associated with the page, as set in the SuperMD frontmatter.

aliases : [String] (see also [any])

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] (see also [any])

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] (see also [any])

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] (see also [any])

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 subpagesAlphabetic () -> [Page] (see also [any])

Same as subpages, but returns the pages in alphabetic order by comparing their titles.

Examples

<div :loop="$page.subpagesAlphabetic()">
  <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()

Returns the URL of the target page.

Examples

$page.link()

fn linkRef () -> String

Returns the URL of the target page, allowing you to specify a fragment id to deep-link to a specific element of the content page.

The id will be checked by Zine and an error will be
reported if it does not exist.

See the SuperMD reference documentation to learn how to give ids to elements.

Examples

$page.linkRef('foo')

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 hasContentSection (String) -> String

Returns true if the page contains a content-section with the given id

Examples

<div :html="$page.hasContentSection('section-id')"></div>
<div :html="$page.hasContentSection('other-section')"></div>

fn contentSections () -> [ContentSection] (see also [any])

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. When inside of a git repository it also gives git-related metadata.

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>

fn git () -> Git

Returns git-related metadata if you are inside a git repository. If you are not or the parsing failes, it will return an error. Packed object are not supported, commit anything to get the metadata.

Examples

<div :text="$build.git()..."></div>

fn git? () -> Git

Returns git-related metadata if you are inside a git repository. If you are not or the parsing failes, it will return null. Packed object are not supported, commit anything to get the metadata.

Examples

<div :if="$build.git?()">...</div>

Git

Information about the current git repository.

Fields

commit_hash : String

The current commit hash.

commit_date : Date

The date of the current commit.

commit_message : String

The commit message of the current commit.

author_name : String

The name of the author of the current commit.

author_email : String

The email of the author of the current commit.

Functions

fn tag () -> String

Returns the tag of the current commit. If the current commit does not have a tag, an error is returned.

Examples

<div :text="$build.git().tag()"></div>
<div :if="$build.git?()"><span :text="$if.tag()"></span></div>

fn tag? () -> String

Returns the tag of the current commit. If the current commit does not have a tag, null is returned.

Examples

<div :if="$build.git().tag?()"><span :text="$if"></span></div>
<div :if="$build.git?()"><span :if="$if.tag?()"><span :text="$if"></span></span></div>

fn branch () -> String

Returns the branch of the current commit. If the current commit does not have a branch, an error is returned.

Examples

<div :text="$build.git().branch()"></div>
<div :if="$build.git?()"><span :text="$if.branch()"></span></div>

fn branch? () -> String

Returns the branch of the current commit. If the current commit does not have a branch, null is returned.

Examples

<div :if="$build.git().branch?()"><span :text="$if"></span></div>
<div :if="$build.git?()"><span :if="$if.branch?()"><span :text="$if"></span></span></div>

Asset

Represents an asset.

Functions

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 sriHash () -> String

Returns the Base64-encoded SHA384 hash of an asset, prefixed with sha384-, for use with Subresource Integrity.

Examples

<script src="$site.asset('foo.js').link()" integrity="$site.asset('foo.js').sriHash()"></script>

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] (see also [any])

Iterates over key-value pairs of a Ziggy map.

Examples

$page.custom.iterate()

fn iterPattern (String) -> [KV] (see also [any])

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

Array

An array of items.

Fields

len : Int

The length of the array.

empty : Bool

True when len is 0.

Functions

fn slice (Int, ?Int) -> [any]

Slices an array from the first value (inclusive) to the second value (exclusive).

The second value can be omitted and defaults to the array’s length, meaning that invoking slice with one argunent produces suffixes of the original sequence (i.e. it removes a prefix from the original sequence).

Note that negative values are not allowed at the moment.

Examples

$page.tags.slice(0,1)

fn at (Int) -> any

Returns the value at the provided index.

Examples

$page.tags.at(0)

KV

A key-value pair.

Fields

key : String

The key string.

value : any

The corresponding value.

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.