Directives

$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.

By calling collapsible you can generate <details> elements:

Example:

># [Example]($block.collapsible(false))
>The title becomes the `<summary>` element!
>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>!

$mathtex : Mathtex

Outputs the given LaTeX formula as a script tag that can be rendered at runtime by JavaScript tools such as Katex, MathJax, Temml, etc. Note that the formula must be enclosed in backticks to avoid collisions with other SuperMD syntax.

This JS based solution is temporary. Zine will eventually implement its own way of outputting MathML at buildtime so that clients won’t need to have JS enabled.

To render math formulas as separate blocks, use this syntax:

```=mathtex
x+\sqrt{1-x^2}
```

Example:

Here's some [`x+\sqrt{1-x^2}`]($mathtex) math. 

This will be rendered by SuperHTML as:

Here's some <script type="math/tex">x+\sqrt{1-x^2}</script> math.

It’s then the user’s responsibility to wire in the necessary JS/CSS dependencies to obtain runtime rendering of math formulas.

The Zine sample site shows a basic setup that uses Temml.

$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.

By calling collapsible you can generate <details> elements:

Example:

># [Example]($block.collapsible(false))
>The title becomes the `<summary>` element!
>Lorem ipsum.

Functions

fn collapsible (bool) -> Block

Render the block as a collapsible element. The argument defines if the block should be open by default or not.

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 size (int, int) -> Image

Sets the width and/or height of the image.

When both dimensions are non-zero, the image will be resized to exactly those dimensions:

[Image caption]($image.asset('example.jpg').size(800, 600))

To specify width while maintaining aspect ratio, set height to 0:

[Image caption]($image.asset('example.jpg').size(800, 0))

To specify height while maintaining aspect ratio, set width to 0:

[Image caption]($image.asset('example.jpg').size(0, 600))

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 alternative (str) -> Link

When linking to a content page, allows to link to a specific alternative version of the page, which can be particularly useful when referencing the RSS feed version of a page.

The string argument is the name of an alrenative as defined in the page’s alternatives frontmatter property.

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.

fn lines (int, int) -> Code

Limit the included code asset to the specified lines. The second argument is inclusive.

[]($code.asset("main.zig").lines(10, 15))

This will include only lines 10 - 15 from the main.zig asset file.

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>!

Mathtex

Outputs the given LaTeX formula as a script tag that can be rendered at runtime by JavaScript tools such as Katex, MathJax, Temml, etc. Note that the formula must be enclosed in backticks to avoid collisions with other SuperMD syntax.

This JS based solution is temporary. Zine will eventually implement its own way of outputting MathML at buildtime so that clients won’t need to have JS enabled.

To render math formulas as separate blocks, use this syntax:

```=mathtex
x+\sqrt{1-x^2}
```

Example:

Here's some [`x+\sqrt{1-x^2}`]($mathtex) math. 

This will be rendered by SuperHTML as:

Here's some <script type="math/tex">x+\sqrt{1-x^2}</script> math.

It’s then the user’s responsibility to wire in the necessary JS/CSS dependencies to obtain runtime rendering of math formulas.

The Zine sample site shows a basic setup that uses Temml.