Components¶

This page pairs rendered components with source that you can copy into a Tarn site. Tarn supplies the colours, borders and icons. Zensical supplies the Markdown syntax. The header toggle shows the light and dark treatments.

For a complete site setup, see Build your first site. For theme settings and colour variables, see Configuration and CSS custom properties.

Admonitions¶

An admonition is a labelled block for supporting information. Tarn groups the twelve standard types into five colour tones. The icons below are Tarn's defaults.

These five rendered blocks show one example of each tone:

The source below produces the first block. The type follows !!!, an optional quoted title follows the type, and the body uses four spaces of indentation.

!!! note "Theme configuration"
    Tarn's settings belong under `project.extra.tarn` in `zensical.toml`.

A collapsible block uses ??? in place of !!!. ???+ starts expanded. Tarn applies the same tones to these blocks. See Zensical's admonition syntax for nesting and other forms.

Code¶

Inline: project.extra.tarn contains Tarn's settings in zensical.toml. Keys: Ctrl+C. Highlight: the selected text.

The source for those inline treatments is:

Inline: `project.extra.tarn` contains Tarn's settings in `zensical.toml`.
Keys: ++ctrl+c++. Highlight: ==the selected text==.

A fenced code block can show a filename, line numbers and selected lines. This example highlights line 3:

1
2
3

[project.theme]
name = "tarn"
logo = "assets/logo.svg"

The complete Markdown source is:

```toml title="zensical.toml" linenums="1" hl_lines="3"
[project.theme]
name = "tarn"
logo = "assets/logo.svg"
```

toml selects syntax highlighting, title supplies the displayed filename, linenums sets the first line number, and hl_lines selects lines to highlight. The logo path is illustrative and requires a matching file in the site's docs directory. This documentation site enables code copy buttons with content.code.copy in its feature list. Add that flag to your site's project.theme.features to display copy buttons globally.

See Zensical's code blocks and formatting references for syntax and Markdown extension configuration.

Content tabs¶

Content tabs group alternative examples. Each tab below contains a complete palette list for one colour mode. A project palette list replaces Tarn's default list, so these examples omit the mode toggle.

[[project.theme.palette]]
scheme = "default"
primary = "custom"
accent = "custom"

[[project.theme.palette]]
scheme = "slate"
primary = "custom"
accent = "custom"

The source uses === followed by a quoted tab label. Each tab's content uses four spaces of indentation:

=== "Light only"

    ```toml
    [[project.theme.palette]]
    scheme = "default"
    primary = "custom"
    accent = "custom"
    ```

=== "Dark only"

    ```toml
    [[project.theme.palette]]
    scheme = "slate"
    primary = "custom"
    accent = "custom"
    ```

Content tabs work without content.tabs.link. This documentation site enables that flag to keep the tutorial's repeated operating-system tabs in sync. Selecting a tab also selects tabs with the same label in other groups. Add the flag to your site's project.theme.features for that behaviour. See Zensical's content tabs reference.

Table¶

Tarn gives tables a border, a header background and a row hover treatment. This table lists three real settings under project.extra.tarn:

| Setting | Type | Default | Effect |
| --- | --- | --- | --- |
| `enabled` | boolean | `true` | Enables badges and navigation decoration. |
| `badges` | boolean | `true` | Shows page badges when `enabled` is also `true`. |
| `navigation` | boolean | `true` | Decorates navigation when `enabled` is also `true`. |

See Configuration for the full settings table.

Buttons¶

Buttons are links with CSS classes. The primary style has a filled background. The secondary style has an outlined border. These examples link to existing pages:

Build your first site Configuration

[Build your first site](../tutorials/first-site.md){ .md-button .md-button--primary }
[Configuration](configuration.md){ .md-button }

The classes follow the link in braces. See Zensical's buttons reference for the syntax.

Diátaxis badges¶

Tarn generates page badges from the page's section or its tarn.type metadata. These specimens show the four generated UI treatments:

Tutorial How-to guide Reference Explanation

Authors control the badge through configuration or page metadata. The HTML spans above demonstrate the appearance and are not the authoring interface. For example, this front matter selects a Reference badge:

---
tarn:
  type: reference
---

See Set or remove a page's badge for the task and Configuration for accepted values and switches.