Annotations

The annotated shortcode lets you pair a content element with an explanatory note. You can use it with code blocks, tabs, or tables. Use --- or  to separate the main content from the note.

Basic usage #

Write your content, add --- as a separator, then write the explanatory note:

{{< annotated >}}
```javascript
console.log("Hello world");
```
---
Explanatory note.
{{< /annotated >}}

Result #

console.log("Hello world");

Explanatory note.

Parameters #

Parameter	Position	Type	Required	Description
`class`	`0`	`string`	No	Additional CSS class for the container.

Code blocks #

Use annotated to pair a code block with its explanation:

{{< annotated >}}
```bash
npm install @example/sdk
```
---
This command installs the `@example/sdk` package via npm.
{{< /annotated >}}

npm install @example/sdk

This command installs the @example/sdk package via npm.

Tabs #

You can combine annotated with tabs to attach a shared explanation to multiple tabs:

{{< annotated >}}
{{< tabs >}}
{{< tab "Greeting" >}}
Hello, this is an example of a shared explanation across multiple tabs.
{{< /tab >}}
{{< tab "Farewell" >}}
Goodbye, this is an example of a shared explanation across multiple tabs.
{{< /tab >}}
{{< /tabs >}}
---
This is an example of a shared explanation across multiple tabs.
{{< /annotated >}}

Greeting

Hello, this is an example of a shared explanation across multiple tabs.

Farewell

Goodbye, this is an example of a shared explanation across multiple tabs.

This is an example of a shared explanation across multiple tabs.

Code tabs #

You can also combine annotated with tabs and tab to attach a shared explanation to multiple code tabs:

{{< annotated >}}
{{< tabs >}}
{{< tab "npm" >}}
```bash
npm install @example/sdk
```
{{< /tab >}}
{{< tab "yarn" >}}
```bash
yarn add @example/sdk
```
{{< /tab >}}
{{< /tabs >}}
---
This package requires Node.js 18 or higher.
{{< /annotated >}}

npm

npm install @example/sdk

yarn

yarn add @example/sdk

This package requires Node.js 18 or higher.

Tables #

You can also pair a table with an explanatory note:

{{< annotated >}}
| Parameter | Type                   | Default |
| :-------- | :--------------------- | :------ |
| `timeout` | {{< type number >}} | `3000`  |
| `retries` | {{< type number >}} | `3`     |
---
The `timeout` value is expressed in milliseconds.
{{< /annotated >}}

Parameter	Type	Default
`timeout`	`number`	`3000`
`retries`	`number`	`3`

The timeout value is expressed in milliseconds.

Alternative separator #

You can use  instead of --- if your content contains horizontal rules:

{{< annotated >}}
```yaml
key: value
```
<!-- split -->
The `key` field accepts any string value.
{{< /annotated >}}

The content below the separator is processed via .Page.RenderString, so it supports Markdown.