Code Examples and Language Tabs
Relevant source files
The following files were used as context for generating this wiki page:
The Datadog documentation uses a flexible tabbing system built with Hugo shortcodes and JavaScript to display content, particularly for multi-language code examples. This system allows users to switch between different versions of content, such as code snippets in various programming languages, and persists their selection across the site for a consistent experience.
There are two primary implementations of tabs: a generic tab system using tabs and tab shortcodes, and a specialized system for code languages that automatically generates tabs based on page metadata. Both are powered by the same underlying client-side script for interactivity.
System Architecture
The tabbing system is composed of server-side Hugo templates (shortcodes and partials) that generate the HTML structure, and a client-side JavaScript component that handles user interaction and state management.
This diagram illustrates the relationship between the core components of the tabbing system.
Generic Tab System
This system is implemented using two Hugo shortcodes: tabs and tab. It is used for creating arbitrary tabbed content.
Sources: layouts/shortcodes/tabs.html, layouts/shortcodes/tab.html, content/ko/code_analysis/_index.md
{{< tabs >}} Shortcode
The tabs shortcode acts as the main container for a tab group. It creates the navigation list (<ul>) and a container for the tab content.
Implementation Details:
- It generates a
divwith the classtabs-wrapperand a uniqueid. - Inside, it creates a
ulwith the classnav-tabsfor the tab buttons. - The
.Innercontent, which should contain one or moretabshortcodes, is rendered within atab-contentdiv.
Sources: layouts/shortcodes/tabs.html:1-21
{{< tab >}} Shortcode
The tab shortcode defines a single tab pane and its corresponding navigation button. It must be nested inside a tabs shortcode.
Parameters:
| Parameter | Type | Description | Required |
|---|---|---|---|
N (1st positional) | string | The text label to display on the tab button. | Yes |
active | bool | If set to true, this tab will be the default active tab on page load. Only one tab should be active. | No |
Implementation Details:
- It appends a list item (
<li>) with a button to the parenttabsshortcode's scratchpad. - It renders its inner content inside a
divwith the classtab-pane. - The
activeparameter adds anactiveclass to both the button and the pane.
Sources: layouts/shortcodes/tab.html:1-30
Example Usage
The following example from a content file shows how to construct a tab group.
{{< tabs >}}
{{% tab "Datadog" %}}
Datadog-hosted scanning allows you to scan your code within Datadog's infrastructure instead of in your CI pipeline.
{{% /tab %}}
{{% tab "CI Pipelines" %}}
If you do not want to scan directly through Datadog, select the scans you want to run (Static Analysis and Software Composition Analysis) and configure your CI pipeline provider accordingly.
{{% /tab %}}
{{< /tabs >}}
Sources: content/ko/code_analysis/_index.md:52-68
Language-Specific Tab System
For documentation pages that provide code examples in multiple languages, a specialized system using the code-lang-tabs.html partial is employed. This system automatically generates tabs based on a page's front matter and its sibling pages.
Sources: layouts/partials/code-lang-tabs.html, content/en/tests/setup/swift.md
Triggering the System
This system is activated when a page's front matter contains type: multi-code-lang.
---
title: Swift Tests
code_lang: swift
type: multi-code-lang
code_lang_weight: 50
---
Sources: content/en/tests/setup/swift.md:2-6
code-lang-tabs.html Partial
This partial is the core of the language-specific tab system. It performs the following logic:
- Finds Sibling Pages: It identifies all pages that are part of the same
multi-code-langgroup. - Sorts Languages: It sorts the found languages based on the
code_lang_weightparameter in each page's front matter. - Generates Tabs: It iterates through the sorted language pages and generates the tab navigation structure. Each tab is a link to the corresponding language-specific page.
- Sets Active Tab: The tab for the current page is marked as active.
The following flowchart shows the logic for generating the language tabs.
Client-Side Interactivity
All tab systems are powered by assets/scripts/components/code-languages.js, which handles the user interactions and state persistence.
Event Handling and State Management
The script listens for clicks on tab buttons and performs the following actions:
- Identify Group: It determines which tab group the clicked button belongs to.
- Update Active State: It removes the
activeclass from the currently active tab and pane within that group and applies it to the clicked tab and its corresponding pane. - Persist Selection: For language tabs (identified by
data-lang-name), it saves the selected language tolocalStorageunder the keycode-lang.
This sequence diagram shows the client-side flow when a user clicks a language tab.
localStorage Persistence
The script uses localStorage to remember the user's preferred code language.
| Key | Value | Description |
|---|---|---|
code-lang | string | The data-lang-name of the last selected language tab (e.g., "swift", "ruby"). |
On page load, the script checks for this key. If a language is stored, it attempts to find a matching tab on the current page and automatically navigate to the corresponding language-specific page. This ensures that if a user selects "Python" on one page, they will see the "Python" version of the next multi-code-lang page they visit.
Sources: assets/scripts/components/code-languages.js:13-29
Conclusion
The combination of Hugo's templating capabilities and targeted client-side JavaScript provides a robust and user-friendly system for displaying tabbed content. The generic tabs/tab shortcodes offer flexibility for any content type, while the specialized multi-code-lang system streamlines the creation of multi-language documentation by automating tab generation based on a "convention over configuration" approach. The use of localStorage enhances the user experience by remembering language preferences across the documentation site.