Project Purpose and Overview
Relevant source files
The following files were used as context for generating this wiki page:This repository contains the Markdown source code for the official Datadog documentation site, which is published at docs.datadoghq.com. It serves as the central hub for creating, managing, and publishing technical documentation for all Datadog products and features. The project uses the Hugo static site generator to build the website from the content within this repository.
The repository's primary purpose is to provide a collaborative platform for both Datadog employees and external contributors to improve the documentation. It establishes a clear set of guidelines for contributions, content style, and technical structure to ensure consistency and quality. The build system is designed to handle a complex documentation suite, including content sourced from external repositories and auto-generated pages for APIs and integrations.
Sources: README.md:3-4, CLAUDE.md:5-6
Project Architecture
The repository is structured to support a large-scale documentation site built with Hugo. It combines content, layout templates, static assets, and a multi-faceted build system to produce the final website.
Sources: CLAUDE.md:21-36
Directory Structure
The key directories that define the site's structure are:
| Directory | Purpose |
|---|---|
content/en/ | Contains the primary English documentation in Markdown format. |
content/{fr,es,ja,ko}/ | Contains translated content, which is managed externally and not intended for direct contribution. |
layouts/ | Holds Hugo templates, including shortcodes used for rendering complex components like multi-language code blocks and integration assets. |
static/ | Stores static assets such as images and fonts. |
assets/ | Contains source assets like SCSS stylesheets and JavaScript that require processing. |
config/ | Contains Hugo configuration files for different environments (development, preview, live). |
Sources: CLAUDE.md:22-28, CONTRIBUTING.md:14-16, CLAUDE.md:41-42
Build System
The documentation site is built using a combination of tools orchestrated by Makefile and yarn scripts.
This diagram shows the core components of the build system. Makefile orchestrates Node.js, Python, and Hugo to process local Markdown and external sources into the final static website.
Sources: README.md:4, CLAUDE.md:29-36, 40-41
- Hugo: The core static site generator that converts Markdown content into HTML pages using templates from the
layoutsdirectory. The site uses the Goldmark renderer, which is CommonMark compliant. - Node.js/Yarn: Manages package dependencies (
package.json), build automation, and asset processing (SCSS, JS). - Python: Used for content processing scripts, fetching integration data, and managing translations.
- Makefile: Orchestrates the entire build process, including installing dependencies and running the various build scripts.
Sources: README.md:4, 46, CLAUDE.md:10-19, 30-33
Contribution Workflow
The repository has a well-defined workflow for contributions from both external developers and internal Datadog staff. All contributions are made via pull requests to the master branch.
Sources: README.md:6-11, 22-44, CONTRIBUTING.md:11-12
Contribution Process Flow
The following diagram illustrates the general process for submitting changes to the documentation.
Sources: README.md:22-44, CLAUDE.md:45-49
Key Requirements for Contributors
- External Contributors: Must fork the repository and create a pull request from their fork.
- Datadog Staff: Must create branches directly from
masterand follow a strict naming convention:<name>/<description>. This format is essential for triggering the CI pipeline and generating a branch preview. - Pull Requests: Draft pull requests should be used for work in progress.
- Deployment: Merging a pull request to
masterautomatically triggers a deployment to the production documentation site.
Sources: README.md:24-44
Content Standards and Style Guide
To maintain quality and consistency, all content must adhere to the standards defined in CONTRIBUTING.md.
General Principles
- Be Direct and Specific: Use simple, clear phrasing.
- Be Objective: Avoid marketing language and focus on clear instructions.
- Be Concise: Rephrase complex sentences to be simpler.
- Use Active Voice: Write in the active voice (e.g., "The Agent sends metrics") rather than passive voice ("Metrics are sent by the Agent").
- Use Inclusive Language: Avoid terms like "master/slave" or "blacklist/whitelist" in favor of "primary/secondary" and "allow list/disallow list".
- Language: All documentation must be written in American English (
en_US).
Sources: CONTRIBUTING.md:14, 20-56, 61-65
Formatting and Syntax
- Markdown: The site uses Goldmark, which is compliant with CommonMark. All markdown files must have a
.mdextension and be named in lowercase. - Code Substitution: Placeholders in code blocks must use the format
<DATADOG_API_KEY>. - Headers:
<h1>headers use Title Case, while<h2>through<h6>use Sentence case. - Links: Use reference-style links (
[link text][1]) with descriptive text.
Sources: README.md:46-50, CONTRIBUTING.md:112-120, 131-140
Special Content Types
Beyond standard documentation pages, the repository manages structured content for Datadog integrations and other complex features.
Integrations
Integrations are a core part of the Datadog ecosystem, and their documentation is highly structured. To build a new integration tile, a developer must provide a set of specific assets.
Sources: developers/integrations/build_integration.md, developers/integrations/check_references.md
Required Integration Assets
The following table lists the key files required when creating a new integration offering.
| Asset File | Description |
|---|---|
manifest.json | Defines metadata for the integration, including its name, author, pricing, and what assets it includes. |
metadata.csv | A list of all out-of-the-box metrics collected by the integration, including metric_name, metric_type, and description. |
| Dashboards | JSON files for pre-built dashboards, located in an assets/dashboards directory. |
| Monitors | JSON files for pre-built monitor templates, located in an assets/monitors directory. |
README.md | The main documentation for the integration, including overview, setup, and data collection details. |
| Logos | SVG files for the integration's logo, stored in an assets/logos directory. |
service_check.json | Describes the service checks performed by the integration. |
Sources: layouts/shortcodes/integration-assets.en.md, developers/integrations/check_references.md:38-40, 75-78, 92-94
Internal Developer Portal (IDP) Documentation
The repository contains comprehensive guides for Datadog products like the Internal Developer Portal (IDP). This content illustrates how the documentation supports complex, multi-component products. The IDP documentation outlines its core features:
- Software Catalog: A real-time inventory of all software architecture components (services, APIs, libraries, etc.).
- Scorecards: A tool to measure adherence to engineering best practices and standards.
- Self-Service Actions: A feature enabling developers to run standardized tasks (e.g., provisioning infrastructure) via a UI.
- Engineering Reports: Dashboards for visualizing quality, reliability, and compliance metrics.
This diagram shows the relationship between the core components of the Internal Developer Portal as described in the documentation.
Summary
The documentation-datadog repository is the definitive source of truth for Datadog's public-facing documentation. It is a sophisticated project that leverages a modern static site generation stack (Hugo, Node.js, Python) to build a comprehensive and high-quality documentation website. The project is built around a strong contribution model that encourages collaboration while enforcing strict standards for content, style, and structure, ensuring that users receive accurate and consistent information.