Global Scope

$section : Section

A content section, used to define a portion of content that can be rendered individually by a template.

$block : Block

When placed at the beginning of a Markdown quote block, the quote block becomes a styleable container for elements.

SuperHTML will automatically give the class block when rendering Block directives.

Example:

>[]($block)
>This is now a block.
>Lorem ipsum.

Differently from Sections, Blocks cannot be rendered independently and can be nested.

Example:

>[]($block)
>This is now a block.
>
>>[]($block.attrs('padded'))
>>This is a nested block.
>>
>
>back to the outer block

A block can optionally wrap a Markdown heading element. In this case
the generated Block will be rendered with two separate sub-containers: one for the block title and one for the body.

Example:

># [Warning]($block.attrs('warning'))
>This is now a block note.
>Lorem ipsum.

$heading : Heading

Allows giving an id and attributes to a heading element.

Example:

# [Title]($heading.id('foo').attrs('bar', 'baz'))

This will be rendered by SuperHTML as:

<h1 id="foo" class="bar baz">Title</h1>

$text : Text

Allows giving an id and attributes to some text.

Example:

Hello [World]($text.id('foo').attrs('bar', 'baz'))!

This will be rendered by SuperHTML as:

Hello <span id="foo" class="bar baz">World</span>!

$link : Link

A link.

$code : Code

An embedded piece of code.

Any text placed between [] will be used as a caption for the snippet.

Example:

[This is the caption]($code.asset('foo.zig'))

$image : Image

An embedded image.

Any text placed between [] will be used as a caption for the image.

Example:

[This is the caption]($image.asset('foo.jpg'))

$video : Video

An embedded video.

Any text placed between [] will be used as a caption for the video.

Example:

[This is the caption]($video.asset('foo.webm'))

anydirective

Each Directive has a different set of properties that can be set. Properties that can be set on all directives are listed here.

Functions

fn id (str) -> anydirective

Sets the unique identifier field of this directive.

fn attrs (str, [str…]) -> anydirective

Appends to the attributes field of this Directive.

fn title (str) -> anydirective

Title for this directive, mostly used as metadata that does not get rendered directly in the page.

fn data (str, str, [str…]) -> anydirective

Adds data key-value pairs of a Directive.

In SuperHTML data key-value pairs can be accessed programmatically in a template when rendering a section, while data will turn into data-foo attributes otherwise.

Section

A content section, used to define a portion of content that can be rendered individually by a template.

Block

When placed at the beginning of a Markdown quote block, the quote block becomes a styleable container for elements.

SuperHTML will automatically give the class block when rendering Block directives.

Example:

>[]($block)
>This is now a block.
>Lorem ipsum.

Differently from Sections, Blocks cannot be rendered independently and can be nested.

Example:

>[]($block)
>This is now a block.
>
>>[]($block.attrs('padded'))
>>This is a nested block.
>>
>
>back to the outer block

A block can optionally wrap a Markdown heading element. In this case
the generated Block will be rendered with two separate sub-containers: one for the block title and one for the body.

Example:

># [Warning]($block.attrs('warning'))
>This is now a block note.
>Lorem ipsum.

Heading

Allows giving an id and attributes to a heading element.

Example:

# [Title]($heading.id('foo').attrs('bar', 'baz'))

This will be rendered by SuperHTML as:

<h1 id="foo" class="bar baz">Title</h1>

Image

An embedded image.

Any text placed between [] will be used as a caption for the image.

Example:

[This is the caption]($image.asset('foo.jpg'))

Functions

fn alt (str) -> Image

An alternative description for this image that accessibility tooling can access.

fn linked (bool) -> Image

Wraps the image in a link to itself.

fn url (str) -> Image

Sets the source location of this directive to an external URL.

fn asset (str) -> Image

Sets the source location of this directive to a page asset.

fn siteAsset (str) -> Image

Sets the source location of this directive to a site asset.

fn buildAsset (str) -> Image

Sets the source location of this directive to a build asset.

Video

An embedded video.

Any text placed between [] will be used as a caption for the video.

Example:

[This is the caption]($video.asset('foo.webm'))

Functions

fn loop (bool) -> Video

If true, the video will seek back to the start upon reaching the end.

fn muted (bool) -> Video

If true, the video will be silenced at start.

fn autoplay (bool) -> Video

If true, the video will start playing automatically.

fn controls (bool) -> Video

If true, the video will display controls (e.g. play/pause, volume).

fn pip (bool) -> Video

If false, clients shouldn’t try to display the video in a Picture-in-Picture context.

fn url (str) -> Video

Sets the source location of this directive to an external URL.

fn asset (str) -> Video

Sets the source location of this directive to a page asset.

fn siteAsset (str) -> Video

Sets the source location of this directive to a site asset.

fn buildAsset (str) -> Video

Sets the source location of this directive to a build asset.

Link

A link.

Functions

fn url (str) -> Link

Sets the source location of this directive to an external URL.

fn asset (str) -> Link

Sets the source location of this directive to a page asset.

fn siteAsset (str) -> Link

Sets the source location of this directive to a site asset.

fn buildAsset (str) -> Link

Sets the source location of this directive to a build asset.

fn page (str, ?str) -> Link

Sets the source location of this directive to a page.

The first argument is a page path, while the second, optional argument is the locale code for mulitlingual websites. In mulitlingual websites, the locale code defaults to the same locale of the current content file.

The path is 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

fn sibling (str, ?str) -> Link

Same as page(), but the reference is relative to the section the current page belongs to.

fn sub (str, ?str) -> Link

Same as page(), but the reference is relative to the current page.

Only works on Section pages (i.e. pages with a index.smd filename).

fn new (bool) -> Link

When true it asks readers to open the link in a new window or tab.

fn ref (str) -> Link

Deep-links to a specific element (like a section or any directive that specifies an id) of either the current page or a target page set with page().

Zine tracks all ids defined in content files so referencing an id that doesn’t exist will result in a build error.

Zine does not track ids defined inside of templates so use unsafeRef to deep-link to those.

fn unsafeRef (str) -> Link

Like ref but Zine will not perform any id checking.

Can be used to deep-link to ids specified in templates.

Code

An embedded piece of code.

Any text placed between [] will be used as a caption for the snippet.

Example:

[This is the caption]($code.asset('foo.zig'))

Functions

fn asset (str) -> Code

Sets the source location of this directive to a page asset.

fn siteAsset (str) -> Code

Sets the source location of this directive to a site asset.

fn buildAsset (str) -> Code

Sets the source location of this directive to a build asset.

fn language (str) -> Code

Sets the language of this code snippet, which is also used for syntax highlighting.

Text

Allows giving an id and attributes to some text.

Example:

Hello [World]($text.id('foo').attrs('bar', 'baz'))!

This will be rendered by SuperHTML as:

Hello <span id="foo" class="bar baz">World</span>!