---
.title = "SuperMD Scripty Reference",
.date = .date("2023-06-16T00:00:00"),
.layout = "scripty-reference.shtml",
---
[]($section.id('menu'))

># [Directives]($block.collapsible(true))
>- [`$section`]($link.unsafeRef("$section"))
>- [`$block`]($link.unsafeRef("$block"))
>- [`$heading`]($link.unsafeRef("$heading"))
>- [`$text`]($link.unsafeRef("$text"))
>- [`$mathtex`]($link.unsafeRef("$mathtex"))
>- [`$link`]($link.unsafeRef("$link"))
>- [`$code`]($link.unsafeRef("$code"))
>- [`$image`]($link.unsafeRef("$image"))
>- [`$video`]($link.unsafeRef("$video"))
>- [`$audio`]($link.unsafeRef("$audio"))

># [anydirective]($block.collapsible(false))
>- [`description`]($link.ref("anydirective"))
>- [`fn id()`]($link.ref("anydirective.id")) 
>- [`fn attrs()`]($link.ref("anydirective.attrs")) 
>- [`fn title()`]($link.ref("anydirective.title")) 
>- [`fn data()`]($link.ref("anydirective.data")) 

># [Section]($block.collapsible(false))
>- [`description`]($link.ref("Section"))

># [Block]($block.collapsible(false))
>- [`description`]($link.ref("Block"))
>- [`fn collapsible()`]($link.ref("Block.collapsible")) 

># [Heading]($block.collapsible(false))
>- [`description`]($link.ref("Heading"))

># [Image]($block.collapsible(false))
>- [`description`]($link.ref("Image"))
>- [`fn alt()`]($link.ref("Image.alt")) 
>- [`fn linked()`]($link.ref("Image.linked")) 
>- [`fn size()`]($link.ref("Image.size")) 
>- [`fn url()`]($link.ref("Image.url")) 
>- [`fn asset()`]($link.ref("Image.asset")) 
>- [`fn siteAsset()`]($link.ref("Image.siteAsset")) 
>- [`fn buildAsset()`]($link.ref("Image.buildAsset")) 

># [Video]($block.collapsible(false))
>- [`description`]($link.ref("Video"))
>- [`fn loop()`]($link.ref("Video.loop")) 
>- [`fn muted()`]($link.ref("Video.muted")) 
>- [`fn autoplay()`]($link.ref("Video.autoplay")) 
>- [`fn controls()`]($link.ref("Video.controls")) 
>- [`fn pip()`]($link.ref("Video.pip")) 
>- [`fn url()`]($link.ref("Video.url")) 
>- [`fn asset()`]($link.ref("Video.asset")) 
>- [`fn siteAsset()`]($link.ref("Video.siteAsset")) 
>- [`fn buildAsset()`]($link.ref("Video.buildAsset")) 

># [Audio]($block.collapsible(false))
>- [`description`]($link.ref("Audio"))
>- [`fn loop()`]($link.ref("Audio.loop")) 
>- [`fn muted()`]($link.ref("Audio.muted")) 
>- [`fn autoplay()`]($link.ref("Audio.autoplay")) 
>- [`fn hide_controls()`]($link.ref("Audio.hide_controls")) 
>- [`fn url()`]($link.ref("Audio.url")) 
>- [`fn asset()`]($link.ref("Audio.asset")) 
>- [`fn siteAsset()`]($link.ref("Audio.siteAsset")) 
>- [`fn buildAsset()`]($link.ref("Audio.buildAsset")) 

># [Link]($block.collapsible(false))
>- [`description`]($link.ref("Link"))
>- [`fn url()`]($link.ref("Link.url")) 
>- [`fn asset()`]($link.ref("Link.asset")) 
>- [`fn siteAsset()`]($link.ref("Link.siteAsset")) 
>- [`fn buildAsset()`]($link.ref("Link.buildAsset")) 
>- [`fn site()`]($link.ref("Link.site")) 
>- [`fn page()`]($link.ref("Link.page")) 
>- [`fn sibling()`]($link.ref("Link.sibling")) 
>- [`fn sub()`]($link.ref("Link.sub")) 
>- [`fn new()`]($link.ref("Link.new")) 
>- [`fn alternative()`]($link.ref("Link.alternative")) 
>- [`fn ref()`]($link.ref("Link.ref")) 
>- [`fn unsafeRef()`]($link.ref("Link.unsafeRef")) 

># [Code]($block.collapsible(false))
>- [`description`]($link.ref("Code"))
>- [`fn asset()`]($link.ref("Code.asset")) 
>- [`fn siteAsset()`]($link.ref("Code.siteAsset")) 
>- [`fn buildAsset()`]($link.ref("Code.buildAsset")) 
>- [`fn language()`]($link.ref("Code.language")) 
>- [`fn lines()`]($link.ref("Code.lines")) 

># [Text]($block.collapsible(false))
>- [`description`]($link.ref("Text"))

># [Mathtex]($block.collapsible(false))
>- [`description`]($link.ref("Mathtex"))
# [Directives]($section.id('directives'))

## [`$section`]($text.id("$section")) : [Section]($link.ref("Section"))

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

## [`$block`]($text.id("$block")) : [Block]($link.ref("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:
```markdown
>[]($block)
>This is now a block.
>Lorem ipsum.
```

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

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

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

>[]($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:
```markdown
># [Warning]($block.attrs('warning'))
>This is now a block note.
>Lorem ipsum.
```
># [Warning]($block.attrs('warning'))
>This is now a block note.
>Lorem ipsum.


By calling `collapsible` you can generate `<details>` elements:


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



## [`$heading`]($text.id("$heading")) : [Heading]($link.ref("Heading"))

Allows giving an id and attributes to a heading element.

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

This will be rendered by SuperHTML as:
```html
<h1 id="foo" class="bar baz">Title</h1>
```

## [`$text`]($text.id("$text")) : [Text]($link.ref("Text"))

Allows giving an id and attributes to some text.

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

This will be rendered by SuperHTML as:
```html
Hello <span id="foo" class="bar baz">World</span>!
```

## [`$mathtex`]($text.id("$mathtex")) : [Mathtex]($link.ref("Mathtex"))

Outputs the given LaTeX formula as a script tag that can be rendered
at runtime by JavaScript tools such as [Katex](https://katex.org),
[MathJax](https://www.mathjax.org/), [Temml](https://temml.org/), 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:
```markdown
Here's some [`x+\sqrt{1-x^2}`]($mathtex) math.
```

This will be rendered by SuperHTML as:
```html
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`]($text.id("$link")) : [Link]($link.ref("Link"))

A link.

## [`$code`]($text.id("$code")) : [Code]($link.ref("Code"))

An embedded piece of code.

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

Example:
```markdown
[This is the caption]($code.asset('foo.zig'))
```

## [`$image`]($text.id("$image")) : [Image]($link.ref("Image"))

An embedded image.

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

Example:
```markdown
[This is the caption]($image.asset('foo.jpg'))
```

## [`$video`]($text.id("$video")) : [Video]($link.ref("Video"))

An embedded video.

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

Example:
```markdown
[This is the caption]($video.asset('foo.webm'))
```

## [`$audio`]($text.id("$audio")) : [Audio]($link.ref("Audio"))

An embedded audio file.

Any text placed between `[]` will be used as a caption for the audio
file.

Example:
```markdown
[This is the caption]($audio.asset('foo.wav'))
```

# [anydirective]($section.id('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

### []($heading.id("anydirective.id")) [`fn`]($link.ref("anydirective.id")) id (str) -> [anydirective]($link.ref("anydirective"))

Sets the unique identifier field of this directive.

### []($heading.id("anydirective.attrs")) [`fn`]($link.ref("anydirective.attrs")) attrs (str, [str...]) -> [anydirective]($link.ref("anydirective"))

Appends to the attributes field of this Directive.

### []($heading.id("anydirective.title")) [`fn`]($link.ref("anydirective.title")) title (str) -> [anydirective]($link.ref("anydirective"))

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

### []($heading.id("anydirective.data")) [`fn`]($link.ref("anydirective.data")) data (str, str, [str...]) -> [anydirective]($link.ref("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]($section.id('Section'))

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

# [Block]($section.id('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:
```markdown
>[]($block)
>This is now a block.
>Lorem ipsum.
```

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

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

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

>[]($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:
```markdown
># [Warning]($block.attrs('warning'))
>This is now a block note.
>Lorem ipsum.
```
># [Warning]($block.attrs('warning'))
>This is now a block note.
>Lorem ipsum.


By calling `collapsible` you can generate `<details>` elements:


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



## Functions

### []($heading.id("Block.collapsible")) [`fn`]($link.ref("Block.collapsible")) collapsible (bool) -> [Block]($link.ref("Block"))

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

# [Heading]($section.id('Heading'))

Allows giving an id and attributes to a heading element.

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

This will be rendered by SuperHTML as:
```html
<h1 id="foo" class="bar baz">Title</h1>
```

# [Image]($section.id('Image'))

An embedded image.

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

Example:
```markdown
[This is the caption]($image.asset('foo.jpg'))
```

## Functions

### []($heading.id("Image.alt")) [`fn`]($link.ref("Image.alt")) alt (str) -> [Image]($link.ref("Image"))

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

### []($heading.id("Image.linked")) [`fn`]($link.ref("Image.linked")) linked (bool) -> [Image]($link.ref("Image"))

Wraps the image in a link to itself.

### []($heading.id("Image.size")) [`fn`]($link.ref("Image.size")) size (int, int) -> [Image]($link.ref("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:
```markdown
[Image caption]($image.asset('example.jpg').size(800,600))
```

To specify width while maintaining aspect ratio, set height to 0:
```markdown
[Image caption]($image.asset('example.jpg').size(800,0))
```

To specify height while maintaining aspect ratio, set width to 0:
```markdown
[Image caption]($image.asset('example.jpg').size(0,600))
```


### []($heading.id("Image.url")) [`fn`]($link.ref("Image.url")) url (str) -> [Image]($link.ref("Image"))

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

### []($heading.id("Image.asset")) [`fn`]($link.ref("Image.asset")) asset (str) -> [Image]($link.ref("Image"))

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

### []($heading.id("Image.siteAsset")) [`fn`]($link.ref("Image.siteAsset")) siteAsset (str) -> [Image]($link.ref("Image"))

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

### []($heading.id("Image.buildAsset")) [`fn`]($link.ref("Image.buildAsset")) buildAsset (str) -> [Image]($link.ref("Image"))

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

# [Video]($section.id('Video'))

An embedded video.

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

Example:
```markdown
[This is the caption]($video.asset('foo.webm'))
```

## Functions

### []($heading.id("Video.loop")) [`fn`]($link.ref("Video.loop")) loop (bool) -> [Video]($link.ref("Video"))

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

### []($heading.id("Video.muted")) [`fn`]($link.ref("Video.muted")) muted (bool) -> [Video]($link.ref("Video"))

If true, the video will be silenced at start.

### []($heading.id("Video.autoplay")) [`fn`]($link.ref("Video.autoplay")) autoplay (bool) -> [Video]($link.ref("Video"))

If true, the video will start playing automatically.

### []($heading.id("Video.controls")) [`fn`]($link.ref("Video.controls")) controls (bool) -> [Video]($link.ref("Video"))

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

### []($heading.id("Video.pip")) [`fn`]($link.ref("Video.pip")) pip (bool) -> [Video]($link.ref("Video"))

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

### []($heading.id("Video.url")) [`fn`]($link.ref("Video.url")) url (str) -> [Video]($link.ref("Video"))

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

### []($heading.id("Video.asset")) [`fn`]($link.ref("Video.asset")) asset (str) -> [Video]($link.ref("Video"))

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

### []($heading.id("Video.siteAsset")) [`fn`]($link.ref("Video.siteAsset")) siteAsset (str) -> [Video]($link.ref("Video"))

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

### []($heading.id("Video.buildAsset")) [`fn`]($link.ref("Video.buildAsset")) buildAsset (str) -> [Video]($link.ref("Video"))

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

# [Audio]($section.id('Audio'))

An embedded audio file.

Any text placed between `[]` will be used as a caption for the audio
file.

Example:
```markdown
[This is the caption]($audio.asset('foo.wav'))
```

## Functions

### []($heading.id("Audio.loop")) [`fn`]($link.ref("Audio.loop")) loop (bool) -> [Audio]($link.ref("Audio"))

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

### []($heading.id("Audio.muted")) [`fn`]($link.ref("Audio.muted")) muted (bool) -> [Audio]($link.ref("Audio"))

If true, the audio file will be silenced at start.

### []($heading.id("Audio.autoplay")) [`fn`]($link.ref("Audio.autoplay")) autoplay (bool) -> [Audio]($link.ref("Audio"))

If true, the audio file will start playing automatically.

### []($heading.id("Audio.hide_controls")) [`fn`]($link.ref("Audio.hide_controls")) hide_controls (bool) -> [Audio]($link.ref("Audio"))

If true, the audio file will hide its controls (e.g. play/pause,
volume).

### []($heading.id("Audio.url")) [`fn`]($link.ref("Audio.url")) url (str) -> [Audio]($link.ref("Audio"))

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

### []($heading.id("Audio.asset")) [`fn`]($link.ref("Audio.asset")) asset (str) -> [Audio]($link.ref("Audio"))

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

### []($heading.id("Audio.siteAsset")) [`fn`]($link.ref("Audio.siteAsset")) siteAsset (str) -> [Audio]($link.ref("Audio"))

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

### []($heading.id("Audio.buildAsset")) [`fn`]($link.ref("Audio.buildAsset")) buildAsset (str) -> [Audio]($link.ref("Audio"))

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

# [Link]($section.id('Link'))

A link.

## Functions

### []($heading.id("Link.url")) [`fn`]($link.ref("Link.url")) url (str) -> [Link]($link.ref("Link"))

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

### []($heading.id("Link.asset")) [`fn`]($link.ref("Link.asset")) asset (str) -> [Link]($link.ref("Link"))

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

### []($heading.id("Link.siteAsset")) [`fn`]($link.ref("Link.siteAsset")) siteAsset (str) -> [Link]($link.ref("Link"))

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

### []($heading.id("Link.buildAsset")) [`fn`]($link.ref("Link.buildAsset")) buildAsset (str) -> [Link]($link.ref("Link"))

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

### []($heading.id("Link.site")) [`fn`]($link.ref("Link.site")) site (?str) -> [Link]($link.ref("Link"))

Sets the source location of this directive to the site's home page.

The only 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.

### []($heading.id("Link.page")) [`fn`]($link.ref("Link.page")) page (str, ?str) -> [Link]($link.ref("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

To link to the website's home page, see `$link.site()`

### []($heading.id("Link.sibling")) [`fn`]($link.ref("Link.sibling")) sibling (str, ?str) -> [Link]($link.ref("Link"))

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

># [NOTE]($block.attrs('note'))
>While section pages define a section, *as pages* they don't
>belong to the section they define.

### []($heading.id("Link.sub")) [`fn`]($link.ref("Link.sub")) sub (str, ?str) -> [Link]($link.ref("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).

### []($heading.id("Link.new")) [`fn`]($link.ref("Link.new")) new (bool) -> [Link]($link.ref("Link"))

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

### []($heading.id("Link.alternative")) [`fn`]($link.ref("Link.alternative")) alternative (str) -> [Link]($link.ref("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.

### []($heading.id("Link.ref")) [`fn`]($link.ref("Link.ref")) ref (str) -> [Link]($link.ref("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.

### []($heading.id("Link.unsafeRef")) [`fn`]($link.ref("Link.unsafeRef")) unsafeRef (str) -> [Link]($link.ref("Link"))

Like `ref` but Zine will not perform any id checking.

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

# [Code]($section.id('Code'))

An embedded piece of code.

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

Example:
```markdown
[This is the caption]($code.asset('foo.zig'))
```

## Functions

### []($heading.id("Code.asset")) [`fn`]($link.ref("Code.asset")) asset (str) -> [Code]($link.ref("Code"))

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

### []($heading.id("Code.siteAsset")) [`fn`]($link.ref("Code.siteAsset")) siteAsset (str) -> [Code]($link.ref("Code"))

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

### []($heading.id("Code.buildAsset")) [`fn`]($link.ref("Code.buildAsset")) buildAsset (str) -> [Code]($link.ref("Code"))

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

### []($heading.id("Code.language")) [`fn`]($link.ref("Code.language")) language (str) -> [Code]($link.ref("Code"))

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

### []($heading.id("Code.lines")) [`fn`]($link.ref("Code.lines")) lines (int, int) -> [Code]($link.ref("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]($section.id('Text'))

Allows giving an id and attributes to some text.

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

This will be rendered by SuperHTML as:
```html
Hello <span id="foo" class="bar baz">World</span>!
```

# [Mathtex]($section.id('Mathtex'))

Outputs the given LaTeX formula as a script tag that can be rendered
at runtime by JavaScript tools such as [Katex](https://katex.org),
[MathJax](https://www.mathjax.org/), [Temml](https://temml.org/), 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:
```markdown
Here's some [`x+\sqrt{1-x^2}`]($mathtex) math.
```

This will be rendered by SuperHTML as:
```html
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.