Creating Custom Shortcodes
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
This documentation site utilizes the Hugo static site generator, which leverages an extensive library of custom shortcodes to render complex components and reusable content blocks within Markdown files. Shortcodes are simple snippets inside a content file that Hugo renders using a predefined template, allowing for dynamic content, consistent styling, and embedding of external media or complex HTML structures without breaking the flow of Markdown.
The project's shortcodes are located in the layouts/shortcodes/ directory. They are used for a variety of purposes, including creating styled callout boxes, embedding videos, generating lists of links, and displaying multi-language code examples. This system allows content creators to use powerful features with a simple, declarative syntax.
Sources: CLAUDE.md:47-52
Shortcode Invocation and Rendering Flow
Shortcodes are invoked within Markdown content files using a specific syntax. The Hugo engine processes these files, identifies the shortcode calls, and replaces them with the rendered HTML output from the corresponding template file in layouts/shortcodes/.
The following diagram illustrates the process from a Markdown file to the final rendered HTML.
This diagram shows how a shortcode in a Markdown file is processed by Hugo, which uses a template to generate HTML that is then included in the final output page.
Sources: content/en/notebooks/guide/build_diagrams_with_mermaidjs.md:15-20, content/en/dashboards/guide/_index.md:14, layouts/shortcodes/callout.html
Available Shortcodes and Usage
The repository contains several custom shortcodes. Below are analyses of some key examples found in the source files.
Callout Shortcode
The callout shortcode is used to create a styled notification box, often to highlight important information or provide a call to action.
*Sources: content/en/internal_developer_portal/overview_pages.md:18-20, layouts/shortcodes/callout.html *
Parameters
The callout shortcode accepts several named parameters to customize its appearance and behavior.
| Parameter | Type | Description | Required |
|---|---|---|---|
url | String | The destination URL for the callout's button. | No |
d_target | String | The data-target attribute for the link, often used to trigger modals (e.g., #signupModal). | No |
btn_hidden | Bool | If true, the call-to-action button is hidden. | No |
header | String | The text to display as the header of the callout box. | No |
.Inner | String | The content to be displayed inside the callout box, placed between the opening and closing shortcode tags. | Yes |
Sources: layouts/shortcodes/callout.html:1-17
Implementation Logic
The callout.html template uses Go template syntax to conditionally render HTML based on the provided parameters.
This flowchart shows the conditional rendering logic within the callout.html shortcode based on the presence of its parameters.
Sources: layouts/shortcodes/callout.html:1-17
Example Usage
{{< callout url="https://www.datadoghq.com/product-preview/developer-overview-page/" d_target="#signupModal" btn_hidden="false" header="Join the Preview for the Developer Overview Page!" >}}
{{< /callout >}}
Sources: content/en/internal_developer_portal/overview_pages.md:18-20
Vimeo Shortcode
The vimeo shortcode provides a simple way to embed a Vimeo video into a page. It creates a responsive video container.
Sources: layouts/shortcodes/vimeo.html
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
0 | String | The Vimeo video ID. | Yes |
1 | String | The title for the iframe. | No |
Sources: layouts/shortcodes/vimeo.html:2-3
Implementation
The template retrieves the video ID and an optional title from the positional parameters and embeds them in an iframe within a styled container.
{{/* layouts/shortcodes/vimeo.html */}}
<div class="video-container">
<iframe src="https://player.vimeo.com/video/{{ .Get 0 }}" webkitallowfullscreen mozallowfullscreen allowfullscreen title="{{ .Get 1 | default "Vimeo video" }}"></iframe>
</div>
Sources: layouts/shortcodes/vimeo.html:1-4
Content Navigation Shortcodes (whatsnext, nextlink)
A common pattern in the documentation is to use the whatsnext and nextlink shortcodes to create "Further Reading" or "Next Steps" sections.
whatsnext: Acts as a container for a list of links, displaying a descriptive header.nextlink: Represents a single link within thewhatsnextcontainer.
Example Usage
{{< whatsnext desc="Planning, Governance & Admin" >}}
{{< nextlink href="dashboards/guide/maintain-relevant-dashboards" >}}Best practices for maintaining relevant dashboards{{< /nextlink >}}
{{< nextlink href="dashboards/guide/powerpacks-best-practices" >}}Powerpacks best practices{{< /nextlink >}}
{{< /whatsnext >}}
Sources: content/en/dashboards/guide/_index.md:14-18
Code Block Shortcode (code-block)
The code-block shortcode is used to display formatted code snippets with additional options beyond standard Markdown fences. It is used, for example, to disable the copy button for a specific block.
Parameters
| Parameter | Type | Description |
|---|---|---|
lang | String | The language of the code for syntax highlighting. |
disable_copy | Boolean | If true, hides the copy-to-clipboard button. |
Example Usage
{{< code-block lang="bash" disable_copy="true" >}}
{{< /code-block >}}
*Sources: [content/en/notebooks/guide/build_diagrams_with_mermaidjs.md:15-23](https://github.com/Alonso-pixel/documentation-datadog/blob/HEAD/content/en/notebooks/guide/build_diagrams_with_mermaidjs.md#L15-L23)*
### Markdown Shortcodes
Shortcodes can also be Markdown files, which allows for including reusable blocks of Markdown content. An example is `integration-assets.en.md`, which contains a Markdown table. This shortcode can be included in other pages to display this table consistently.
```markdown
{{< partial name="integration-assets.en.md" >}}
The usage of this type of shortcode is inferred from its file type and location. The integration-assets.en.md file itself is a Markdown table definition.
Sources: layouts/shortcodes/integration-assets.en.md
Related Content Rendering
While not strictly shortcodes, the project also uses "partials" for rendering reusable content, such as images. The contribution guidelines refer to a wiki page for more information on image partials, indicating a system for standardized image embedding. This follows a similar principle to shortcodes: abstracting complex or repetitive HTML into a reusable template.
Sources: CONTRIBUTING.md:148-150
Conclusion
The use of Hugo shortcodes is a cornerstone of the content strategy for the Datadog documentation repository. They enable developers and technical writers to create rich, interactive, and consistently styled content using simple, declarative syntax within Markdown. The library of custom shortcodes in layouts/shortcodes/ provides functionality for callouts, media embedding, navigation blocks, and more, streamlining the content creation process and ensuring a high-quality user experience on the documentation site.