Using Shortcodes

Relevant source files

The following files were used as context for generating this wiki page:

• layouts/shortcodes/callout.html
• layouts/shortcodes/tabs.html
• layouts/shortcodes/video.html
• layouts/shortcodes/integration-assets.en.md
• content/en/all_guides.md
• content/en/developers/integrations/check_references.md
• content/en/tests/setup/junit_xml.md
• content/en/notebooks/guide/build_diagrams_with_mermaidjs.md
• content/en/incident_response/status_pages/_index.md

Shortcodes are a feature of the Hugo static site generator that allow for the insertion of predefined templates into markdown content. They serve as a way to extend markdown's capabilities, enabling the creation of complex HTML components like styled callouts, tabbed interfaces, and embedded media with simple, reusable syntax. This system helps maintain consistency and simplifies content creation by abstracting away complex HTML.

All shortcode template files are located in the layouts/shortcodes/ directory. They are invoked within markdown files using either {{< shortcode >}} or {{% shortcode %}} syntax. The % delimiter allows for markdown rendering within the shortcode's inner content.

Sources: CLAUDE.md, README.md

Informational Shortcodes

This category includes shortcodes designed to display informational content in a structured and visually distinct manner.

Callouts

The callout shortcode creates a styled alert box, often used to highlight important information, warnings, or links to previews.

Sources: layouts/shortcodes/callout.html, content/en/incident_response/status_pages/_index.md:23-25, content/en/tests/setup/junit_xml.md:189-191

Usage:

{{< callout url="..." d_target="..." btn_hidden="false" header="..." >}}
This is the inner content of the callout.
{{< /callout >}}

Parameters:

Parameter	Type	Required	Description
header	String	Optional	The title text displayed at the top of the callout.
url	String	Optional	The destination URL for a button within the callout.
d_target	String	Optional	The target for the URL, often used for modal pop-ups (e.g., #signupModal).
btn_hidden	Boolean	Optional	If true, hides the callout button even if a url is provided.
.Inner	String	Optional	The main text content displayed inside the callout.

The following diagram illustrates the logic for rendering the button within the callout shortcode.

What's Next Sections

The whatsnext and nextlink shortcodes work together to create structured "Further Reading" or "What's Next" sections, providing a consistent format for listing related documentation pages.

Sources: content/en/all_guides.md, content/en/dashboards/guide/_index.md

Usage:

{{< whatsnext desc="Section Title:" >}}
    {{< nextlink href="/path/to/page1" >}}Link Text 1{{< /nextlink >}}
    {{< nextlink href="/path/to/page2" >}}Link Text 2{{< /nextlink >}}
{{< /whatsnext >}}

whatsnext

This is the container shortcode.

Parameter	Type	Required	Description
desc	String	Yes	The title displayed above the list of links.

nextlink

This shortcode creates an individual link item within a whatsnext block.

Parameter	Type	Required	Description
href	String	Yes	The URL path for the link.
.Inner	String	Yes	The display text for the link.

This diagram shows the relationship between the whatsnext and nextlink shortcodes.

Structural Shortcodes

These shortcodes are used to build complex layouts and structures within a markdown page.

Tabs

The tabs and tab shortcodes are used to create a tabbed content area, allowing users to switch between different panes of information. This is commonly used for showing code examples in multiple languages.

Sources: layouts/shortcodes/tabs.html, content/en/tests/setup/junit_xml.md:65-103

Usage:
The tabs shortcode acts as a wrapper for one or more tab shortcodes. The tab shortcode must be used with the % delimiter to allow its inner content to be processed.

{{< tabs >}}
{{% tab "Tab 1 Title" %}}
Content for the first tab.
{{% /tab %}}
{{% tab "Tab 2 Title" %}}
Content for the second tab.
{{% /tab %}}
{{< /tabs >}}

The tabs.html template generates a unique ID for the tab group and then processes the inner tab shortcodes to build the navigation and content panes.

Media Shortcodes

These shortcodes facilitate the embedding of media like videos and images.

Video

The video shortcode is used to embed MP4 video files directly into the page.

Sources: layouts/shortcodes/video.html, CONTRIBUTING.md

Usage:

{{< video src="/path/to/video.mp4" alt="Description" style="width:100%;" >}}

Parameters:

Parameter	Type	Required	Description
src	String	Yes	The path to the video file.
alt	String	Yes	Alternative text for accessibility.
style	String	Optional	Inline CSS styles to apply to the video tag.

The shortcode generates a <video> element with autoplay, loop, muted, and playsinline attributes, making it suitable for silent, looping decorative videos.

Sources: layouts/shortcodes/video.html:1-4

Images with Video Capability

While there is a dedicated video shortcode, the more common pattern observed is using the img shortcode with a video=true parameter. This suggests the img shortcode has an extended functionality to handle video embedding.

Usage:

{{< img src="/notebooks/guide/build_diagrams_with_mermaidjs/build-diagram-mermaidjs.mp4" alt="Example video" video=true style="width:100%;" >}}

This usage implies that when video=true is passed, the img shortcode internally renders a <video> tag instead of an <img> tag, likely reusing logic similar to the video.html shortcode.

Sources: content/en/notebooks/guide/build_diagrams_with_mermaidjs.md:32, content/en/incident_response/status_pages/_index.md:13

Content-Specific Shortcodes

The repository also contains highly specific shortcodes designed to pull in and render content for particular documentation sections, such as for integrations.

integration-assets-reference

This shortcode is used to display a table of assets required for a Datadog integration. It appears to work by including a predefined markdown file as its content.

Usage:

{{% integration-assets-reference %}}

This shortcode, when called in content/en/developers/integrations/check_references.md, renders the content from layouts/shortcodes/integration-assets.en.md. This file contains a markdown table detailing assets like README, manifest.json, and metadata.csv. This approach allows the asset reference table to be centrally managed and reused.

Sources: content/en/developers/integrations/check_references.md:46, layouts/shortcodes/integration-assets.en.md