Snippets

A snippet is a file in snippets/ that your writing and templates place by calling its name.

Write a snippet

In snippets/book.html:

<p class="book"><cite>{{ title }}</cite> by {{ author }}</p>

A snippet is HTML with places for values, written as a template is. A call names it by its file’s name without .html, here book, in the letters a to z, digits and _. A snippet can call another.

Call it from the writing

@book(title='Post 1', author='Name')

@book(...) places the snippet there, on a line of its own or inside a sentence. Writing has how a call’s values are written.

Wrap writing in a snippet

In snippets/aside.html:

<aside class="{{ kind }}">{{ body }}</aside>

In the writing:

@aside(kind='tip')
Writing read as *Markdown*, lists and all.
@end

A snippet that shows body wraps writing. Its call stands on a line of its own and takes the lines below it, up to a line holding only @end. They are read as Markdown and handed to the snippet as body. Such calls can be nested.

Call it from a template

In templates/folder.html:

{% for post in page.posts %}
{{ card(post) }}
{% endfor %}

A template calls a snippet inside {{ }}: here snippets/card.html, once for each post, handed the post. Values are handed as in the writing, by name or in order: {{ book(title=page.title, author=page.book.author) }}.

Called inside an attribute, as in href="{{ address_of(tag) }}", a snippet is written without the line break that ends its file.

A snippet called with no values, as {{ filed() }}, shows what it needs of page. A new site’s templates call these:

line, entry, short and thumb each write a list item, so each is called inside <ol> or <ul>.

What a snippet is handed

A snippet sees only what its call hands it, page and site, and what it sets itself.

Hand it values

A snippet takes each name it shows. Its first line, the takes line, names the values a call may give without names, in order. In snippets/book.html:

{# takes title, author #}
<p class="book"><cite>{{ title }}</cite> by {{ author }}</p>

A takes line names two at most. A name ending ... takes any number of values, handed as one list:

{# takes names... #}
<p class="byline">{{ names | join(", ") }}</p>

Pieces of the writing

In snippets/markdown/heading.html:

<h{{ level }} id="{{ id }}">{{ body }}</h{{ level }}>
<a href="#{{ id }}" class="heading-anchor">#</a>

A file in snippets/markdown/ builds one piece of the writing your own way. This one gives every heading a link to itself.

Each file is handed these, and page and site. A value the writing doesn’t give, such as a link’s title, is empty. A body is HTML Statac built, shown as it is.

outside

true where the address leads to another site: a host other than the one in the site’s url and those also_at names.

alt, width, height, photo

alt is the description in the brackets, or else the one in the picture’s own file. width and height are in pixels where the size is known. photo is the picture as page.photo gives it, where the address is a file of the site.

language, caption

The first word after the opening fence, and the rest of that line. Where the first word is a file’s name, language is the language the name gives and caption is the whole line.

number, shown

number is always written 0 to 9. shown is the same number in the digits of the page’s language: ۱ on a Persian page.

label

What a screen reader says for the link back to the text: “back to the text” in English, and in any other language the back_to_the_text line of the site’s file for it, or empty where it has none.

Without a file of your own

• No call reaches these files: @heading(...) calls snippets/heading.html.
• Where the file for a heading, a code block, a callout or the notes writes only spaces, the piece leaves nothing behind.
• Text a template reads with the markdown filter is built by link.html, code.html, inline_code.html and callout.html only.

Number lines or pick them out

In snippets/markdown/code.html:

<pre class="numbered"{% if caption %} data-lines="{{ caption }}"{% endif %}><code{% if language %} class="language-{{ language }}"{% endif %}>{{ code }}</code></pre>

Statac doesn’t number a block’s lines or pick lines out, but a library that runs in the reader’s browser can. This file hands it the code as written, with what follows the language as the lines to pick out: a block opening rust 2,4 is built as <pre class="numbered" data-lines="2,4"><code class="language-rust">.

Place the library’s script in the layout’s <head> as any script: {{ js("lines.js") }}. Where the library brings its own colours, take {{ css("code.css") }} out of the layout and add quiet: [code-colours-not-loaded] to statac.yaml.

Why not include?

{% include "card.html" %}

Statac refuses include, import and from. A snippet call is the one way to place a piece of a page, so a snippet always says what it was handed. For a frame many templates share, use extends.

Where next?

• Writing: how a call’s values are written, calls inside HTML, and a call shown as text
• Templates: what a template sees, extends, and filters such as markdown
• Pictures: showing a picture from a snippet with page.photo
• The starter: every snippet a new site has