Content & Typography Shortcodes

Documentation and live specimens for callouts, code blocks, figures, status tags, tooltips, audio narration, math typesetting, and the AI modifier.

Read Time: 4 min

Content shortcodes enhance prose readability with callouts, syntax-highlighted code snippets, captioned figures, status badges, mathematical notation, and AI transparency modifiers.

1. Carbon AI Label (ai-label)

The ai-label shortcode implements the official IBM Carbon Design System v11 AILabel component (cds--ai-label). It provides a standardized mechanism to disclose AI-synthesized or assisted text.

When clicked, the badge opens an explainability popover dialog detailing why and how the content was produced.

Parameters

ParameterTypeDefaultDescription
textStringOptionalExplanation text inside the popover
headingString"AI-generated content"Title inside the popover dialog
sizeString"sm"Size variant (xs, sm, md, lg)
inlineBooleanfalseWhen true, displays as a compact inline token

Standalone Example

AI-generated content

This summary text was generated by an AI model to illustrate how technical writers can provide full explainability for machine-assisted drafts.

1

{{< ai-label text="This summary text was generated by an AI model to illustrate how technical writers can provide full explainability for machine-assisted drafts." />}}

Paired Shortcode Example

AI Content Notice

This section contains synthetic data generated using a large language model to test table pagination and sorting behaviors without relying on private datasets.

1
2
3

{{< ai-label heading="AI Content Notice" >}}
This section contains synthetic data generated using a large language model to test table pagination and sorting behaviors without relying on private datasets.
{{< /ai-label >}}

2. Callouts & Editorial Asides (callout)

The callout shortcode highlights crucial context, warnings, tips, and AI disclosures.

Parameters

ParameterTypeDefaultDescription
typeString"info"Callout type (info, success, warning, error, ai)
titleStringOptionalHeader title for the callout
closeableBooleanfalseWhen true, implements the official Carbon React ActionableNotification with an accessible close button
actionTextStringOptionalLabel for action button (converts to ActionableNotification)
actionHrefStringOptionalTarget link URL for the action button
lowContrastBooleanfalseWhen true, displays lower contrast container styling
hide_iconBooleanfalseWhen true, hides the leading status icon

Examples

Hugo Extended edition v0.149.0 or higher is required to compile Dart Sass and process ESBuild modules.
All fonts, scripts, and vector assets are bundled directly from origin, ensuring privacy and compliance with strict data regulations.
Remember to initialize submodules with git submodule update --init --recursive when cloning for the first time. This notification is dismissible via the close button.
Explore comprehensive instructions for configuring sites, layouts, and data engines.
Getting Started
This callout uses the type="ai" modifier, rendering Carbon’s purple accent border and AI icon to signal synthesized documentation prose.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{{< callout type="info" title="System Requirement" >}}
Hugo Extended edition v0.149.0 or higher is required to compile Dart Sass and process ESBuild modules.
{{< /callout >}}

{{< callout type="warning" title="Submodule Update Notice" closeable="true" >}}
Dismissible callout rendered using Carbon React ActionableNotification pattern.
{{< /callout >}}

{{< callout type="info" title="Interactive Quickstart" actionText="Getting Started" actionHref="/docs/" >}}
Explore comprehensive instructions for configuring sites, layouts, and data engines.
{{< /callout >}}

{{< callout type="ai" title="AI-Assisted Section" >}}
This callout uses the `type="ai"` modifier, rendering Carbon's purple accent border and AI icon to signal synthesized documentation prose.
{{< /callout >}}

3. Code Snippets & File Viewers (code-snippet, code-file)

Code Snippet (code-snippet)

Renders a terminal or code block with one-click clipboard copying.

# Install Hugo Extended on macOS via Homebrew brew install hugo # Clone and run local preview git clone https://github.com/caldeira-cc/hugo-theme-carbon.git cd hugo-theme-carbon/exampleSite hugo server -p 1316
1
2
3
4

{{< code-snippet type="multi" >}}
# Install Hugo Extended on macOS via Homebrew
brew install hugo
{{< /code-snippet >}}

Code File Viewer (code-file)

Renders a labeled file viewer displaying file path, line count, and a copy button:

yaml . 

baseURL: "https://example.org/"
title: "Production Portal"
theme: "hugo-theme-carbon"
params:
  carbon:
    useLocalFonts: true
    defaultThemeMode: "system"

1
2
3
4

{{< code-file path="config/_default/hugo.yaml" lang="yaml" lines="true" >}}
baseURL: "https://example.org/"
title: "Production Portal"
{{< /code-file >}}

4. Status Tags (tag)

Tags categorize content and convey status. They map directly to Carbon tag color tokens.

Examples

#Core Engine #Passing Tests #Carbon v11 #Deprecated #Draft #RFC 7946
1
2
3

{{< tag type="blue" text="Core Engine" >}}
{{< tag type="green" text="Passing Tests" >}}
{{< tag type="purple" text="Carbon v11" >}}

5. Tooltips (tooltip)

Tooltips provide contextual definitions or extra information on hover and focus.

Hover to inspect 2x Grid details IBM Carbon uses a fluid 16-column layout with 8px mini-unit intervals.
1
2
3

{{< tooltip text="IBM Carbon uses a fluid 16-column layout with 8px mini-unit intervals." >}}
Hover to inspect 2x Grid details
{{< /tooltip >}}

6. Mathematical Typesetting (math)

The math shortcode renders mathematical equations via KaTeX using self-hosted IBM Plex Math OpenType fonts without runtime network latency:

$$f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi)\,e^{2 \pi i \xi x} \,d\xi$$
1
2
3

{{< math >}}
f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi)\,e^{2 \pi i \xi x} \,d\xi
{{< /math >}}

7. Read-Aloud Audio Player (read-aloud)

The read-aloud shortcode provides accessibility audio narration using the browser’s native SpeechSynthesis API:

Listen to this article
Ready
1

{{< read-aloud text="The Hugo Carbon theme incorporates high accessibility standards, including text-to-speech audio narration." label="Listen to documentation excerpt" >}}