Directives

Directives are block-level extras written with ::: fences. They render as HTML without JavaScript; the tabs directive is enhanced by a small script in the built-in layout.

Each example below shows the result and the Markdown that produces it. Switching one example to Markdown switches them all.

Admonitions

Five kinds are built in: note, tip, info, warning and danger.

 1:::note
 2Something worth knowing.
 3:::
 4
 5:::tip
 6A shortcut or a good habit.
 7:::
 8
 9:::info
10Extra context.
11:::
12
13:::warning
14Something that may cause trouble.
15:::
16
17:::danger
18Something that can lose data.
19:::

Titles

A title in square brackets replaces the plain box with a labelled one. The title is plain text.

1:::tip[Live reload]
2Run `tryck dev` and edit any file in `content/`. The browser reloads on save.
3:::

Any Markdown inside

The body is ordinary Markdown: lists, code blocks, tables and links all work.

 1:::warning[Before you upgrade]
 21. Back up `dist/` if you deploy it by hand.
 32. Run a clean build:
 4
 5   ```sh
 6   tryck build
 7   ```
 8
 93. Check the output for `link.broken` errors. See [Diagnostics](../07-diagnostics.md).
10:::

Each admonition renders as <aside class="admonition admonition-<kind>">, with a <p class="admonition-title"> when it has a title. The colours come from the --note, --tip, --info, --warning and --danger CSS variables of the built-in theme.

Details

:::details[summary] renders a native collapsible <details> element. Without a summary it reads "Details".

1Built 24 pages, copied 1 files, 0 warnings, 0 errors in 9ms

1:::details[Show the full output]
2```text
3Built 24 pages, copied 1 files, 0 warnings, 0 errors in 9ms
4```
5:::

Add {open} to show it expanded:

1:::details[Expanded by default]{open}
2Click the summary to fold it.
3:::

Tabs

:::tabs holds one or more @tab Label sections. A tab can contain other directives; see Nesting for when a longer fence helps.

1x := 1

1const x = 1;

1x = 1

The Markdown for these tabs:

 1:::tabs
 2@tab Go
 3```go
 4x := 1
 5```
 6@tab TypeScript
 7```ts
 8const x = 1;
 9```
10@tab Python
11```python
12x = 1
13```
14:::

Without JavaScript the tab list is hidden and every panel shows with its label, so the content is always readable. With JavaScript the built-in layout shows one panel at a time. A tab can hold any directive, including another set of tabs.

Synced groups

Tab sets with the same group switch together: pick a tab in one and the others follow. The choice is remembered in the browser, so it holds on other pages too. Try it with these two sets:

1tar xzf tryck_linux_amd64.tar.gz tryck

1tar xzf tryck_darwin_arm64.tar.gz tryck

1sudo mv tryck /usr/local/bin/

1sudo mv tryck /usr/local/bin/

Both start with ::::tabs{group=os} and use the same tab labels:

1:::tabs{group=os}
2@tab Linux
3```sh
4tar xzf tryck_linux_amd64.tar.gz tryck
5```
6@tab macOS
7...
8:::

Tabs sync by label, so the labels must match exactly.

Nesting

A closing fence needs at least as many colons as its opening fence, and closes the innermost open directive. Nesting works with equal fences; a longer outer fence is easier to read.

1::::warning[Outer]
2:::note[Inner]
3Closed by the three-colon fence.
4:::
5Closed by the four-colon fence.
6::::

Content inside a fenced code block or raw HTML block is never treated as a directive. That is how the Markdown tabs on this page show directive source.

Attributes

Any directive takes a trailing {...} block:

1:::note[Title]{#custom-id .extra-class}
2Content.
3:::

Values with spaces, / or other punctuation need double quotes: {title="Read this"}. Anything else, including event handlers, is dropped. An attribute block that cannot be parsed, such as one with an unclosed quote, is ignored with a directive.attrs warning.

Unknown directives

A ::: name with no renderer still renders, as <div class="directive directive-<name>">, and the build reports a directive.unknown warning. The content is never lost. To give a name its own HTML, add a template in layouts/directives/; see Custom directives.

Edit this page on GitHub