Working with Images and Static Assets
Relevant source files
The following files were used as context for generating this wiki page:This document outlines how images and other static assets are managed and utilized within the Datadog documentation project. The project is built with the Hugo static site generator, which dictates the structure and handling of these assets. The primary location for all static files is the static/ directory at the root of the repository.
Assets include images (PNG, SVG), videos (MP4), and data files (JSON) that are used across the documentation pages. Images are typically rendered using a custom Hugo shortcode, img, which provides flexibility for styling and handling different media types. For integrations, a specific structure of assets is required, including logos, media for carousels, and JSON definitions for dashboards and monitors.
Sources: CLAUDE.md, README.md, layouts/shortcodes/integration-assets.en.md
Asset Storage and Organization
All static assets are stored within the static/ directory. This directory's contents are copied to the root of the final built site. The internal structure of the static/ directory helps organize different types of assets.
Sources: CLAUDE.md
Directory Structure
static/images/: Contains image files like PNGs used in documentation pages. An example isedit_link.png, which is used in the mainREADME.mdto highlight the "Edit" button on documentation pages.static/resources/json/: Holds static JSON files. For instance,agent-version-dashboard.jsonis a JSON definition for a dashboard, likely used for import or as a downloadable resource.assets/(for integrations): When building an integration, assets like logos, dashboards, and monitors are often nested within anassetsdirectory specific to that integration.
Sources: README.md, static/images/edit_link.png, static/resources/json/agent-version-dashboard.json, layouts/shortcodes/integration-assets.en.md
Image and Video Rendering
A custom Hugo shortcode, img, is the standard method for embedding images and videos into Markdown content. This provides a consistent way to handle media and apply specific styling or attributes.
Sources: layouts/shortcodes/img.html, CONTRIBUTING.md:144-146
The img Shortcode
The img shortcode is defined in layouts/shortcodes/img.html. It processes parameters to generate the appropriate HTML <video> or <img> tag.
Parameters
| Parameter | Description | Example Usage |
|---|---|---|
src | Required. The path to the image or video file relative to the static/ directory. | src="tracing/software_catalog/dev-onboarding.png" |
alt | Required for images. The alternative text for the image. | alt="A service's home page..." |
style | Optional. Inline CSS styles to apply to the image. Used for scaling. | style="width:100%;" |
video | Optional. A boolean (true) to indicate the source is a video, which renders a <video> tag. | video=true |
responsive | Optional. A boolean (true) to add a responsive-img class. | responsive="true" |
Sources: layouts/shortcodes/img.html, CONTRIBUTING.md:144-146, content/en/internal_developer_portal/use_cases/dev_onboarding.md:18
Usage Example
The following is an example of how the img shortcode is used within a Markdown file to display an image.
{{< img src="tracing/software_catalog/dev-onboarding-use-case-overview.png" alt="A service's home page, showing information like documentation and repository links, service owners, and on-call details." >}}
Sources: content/en/internal_developer_portal/use_cases/dev_onboarding.md:18
Rendering Flow
The diagram below illustrates how a Markdown file containing the img shortcode is processed by Hugo to produce the final HTML.
This diagram shows the logic within the img.html shortcode, which checks for a video parameter to decide whether to render an <img> or <video> element.
Sources: layouts/shortcodes/img.html
Integration-Specific Assets
Integrations have a standardized set of assets that include media, logos, and configuration files. These assets are crucial for the integration's presentation on the Datadog Marketplace and within the UI.
The following table, derived from layouts/shortcodes/integration-assets.en.md, summarizes the required assets for an integration.
| Asset Name | Description - |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-
| Media | Images (.png, .jpg) and videos for the integration tile's media carousel. Technology Partners can use .png to reduce compression. - |
| Manifest.json | A JSON object defining metadata such as manifest_version, tile, author, pricing, and assets. - |
| Dashboards | JSON files for out-of-the-box dashboards, placed in an assets/dashboards folder. - |
| Monitors | JSON files for out-of-the-box monitors, placed in an assets/monitors folder. - |
| Logos | At least one SVG file for light and dark modes, placed in an assets/logos folder or directly in assets. - |
Sources: layouts/shortcodes/integration-assets.en.md
The following diagram shows the typical file structure for an integration's assets.
This illustrates how different asset types, including JSON definitions and media files, are organized within an integration's directory structure.
Sources: layouts/shortcodes/integration-assets.en.md
Conclusion
The project maintains a clear and organized approach to managing static assets by centralizing them in the static/ directory. The use of a custom img shortcode standardizes the rendering of images and videos, providing flexibility for different use cases. For Datadog integrations, a well-defined asset structure ensures that all necessary media, logos, and JSON-based configurations like dashboards and monitors are correctly packaged, contributing to a consistent user experience on the platform.
Sources: CLAUDE.md, layouts/shortcodes/img.html, layouts/shortcodes/integration-assets.en.md