# Datadog Documentation

The Datadog Documentation repository is the source for docs.datadoghq.com, built using Hugo static site generator. It provides comprehensive documentation for Datadog's observability platform, covering infrastructure monitoring, APM (Application Performance Monitoring), log management, security monitoring, and hundreds of integrations. The repository combines markdown content with Hugo templates, shortcodes, and automated build scripts that pull API examples from multiple language-specific client repositories.

The documentation architecture supports multi-language content (English, French, Japanese, Korean, Spanish), with English as the primary language. The API reference documentation is auto-generated from OpenAPI specifications (v1 and v2) stored in YAML format, with code examples dynamically pulled from Datadog's official API client libraries for Go, Java, Python, Ruby, TypeScript, and Rust. The build system uses Make, Node.js, and Python scripts to orchestrate content fetching, processing, and static site generation.

## Development Commands

### Start Local Development Server

Run the full development build including external dependencies and start the Hugo server on port 1313.

```bash
# Full build with all dependencies (recommended for first run)
make start

# Quick start without external content (faster iteration)
make start-no-pre-build

# Start with integration data from websites-sources
make start-sources

# Docker-based development
make start-docker
```

### Build for Production

Generate the production-ready static site with minification.

```bash
# Production build
yarn build

# Preview environment build (includes drafts and future content)
yarn run build:preview

# Live environment build
yarn run build:live
```

### Clean Generated Files

Remove build artifacts and generated content.

```bash
# Clean Hugo-generated files
make clean

# Clean everything including node_modules and virtual environments
make clean-all

# Clean only API examples
make clean-examples
```

## Content Structure

### Create New Documentation Page

Documentation pages use Hugo frontmatter for metadata and markdown for content.

```markdown
---
title: My New Feature
description: Learn how to use my new feature with Datadog
aliases:
    - /old-path/to-feature
    - /legacy/feature-name
further_reading:
    - link: "/related/topic/"
      tag: "Documentation"
      text: "Related Topic Guide"
    - link: "https://www.datadoghq.com/blog/my-feature/"
      tag: "Blog"
      text: "My Feature Announcement"
cascade:
    algolia:
        rank: 50
        category: Getting Started
---

## Overview

The overview section explains what this feature does and who should use it.

## Prerequisites

Before you begin, ensure you have:
- An active Datadog account
- The Datadog Agent installed
- API and application keys configured

## Setup

Follow these steps to configure the feature:

1. Navigate to **Settings** > **My Feature**.
2. Click **Enable**.
3. Configure the required parameters.

## Further Reading

{{< partial name="whats-next/whats-next.html" >}}
```

### Multi-Language Code Examples

Use the programming-lang-wrapper shortcode for code examples across multiple languages.

```markdown
{{< programming-lang-wrapper langs="python,ruby,go,java" >}}

{{< programming-lang lang="python" >}}
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.metrics_api import MetricsAPI

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = MetricsAPI(api_client)
    response = api_instance.list_tag_configurations()
    print(response)
{{< /programming-lang >}}

{{< programming-lang lang="ruby" >}}
require 'datadog_api_client'

api_instance = DatadogAPIClient::V2::MetricsAPI.new
p api_instance.list_tag_configurations
{{< /programming-lang >}}

{{< programming-lang lang="go" >}}
package main

import (
    "context"
    "fmt"
    "github.com/DataDog/datadog-api-client-go/v2/api/datadog"
    "github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
    ctx := datadog.NewDefaultContext(context.Background())
    configuration := datadog.NewConfiguration()
    apiClient := datadog.NewAPIClient(configuration)
    api := datadogV2.NewMetricsApi(apiClient)
    resp, r, err := api.ListTagConfigurations(ctx)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\nResponse: %v\n", err, r)
    }
    fmt.Fprintf(os.Stdout, "Response: %v\n", resp)
}
{{< /programming-lang >}}

{{< programming-lang lang="java" >}}
import com.datadog.api.client.ApiClient;
import com.datadog.api.client.v2.api.MetricsApi;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        MetricsApi apiInstance = new MetricsApi(defaultClient);
        try {
            apiInstance.listTagConfigurations();
        } catch (Exception e) {
            System.err.println("Exception: " + e);
        }
    }
}
{{< /programming-lang >}}

{{< /programming-lang-wrapper >}}
```

## Hugo Shortcodes

### Tabbed Content

Display content in tabs for different operating systems, configurations, or options.

```markdown
{{< tabs >}}
{{% tab "Linux" %}}

Install the Datadog Agent on Linux:

```bash
DD_API_KEY=<YOUR_API_KEY> DD_SITE="datadoghq.com" bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"
```

{{% /tab %}}
{{% tab "Windows" %}}

Install the Datadog Agent on Windows using PowerShell:

```powershell
$env:DD_API_KEY="<YOUR_API_KEY>"
$env:DD_SITE="datadoghq.com"
. { iwr -useb https://install.datadoghq.com/scripts/install_script_agent7.ps1 } | iex
```

{{% /tab %}}
{{% tab "macOS" %}}

Install the Datadog Agent on macOS:

```bash
DD_API_KEY=<YOUR_API_KEY> DD_SITE="datadoghq.com" bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"
```

{{% /tab %}}
{{< /tabs >}}
```

### Site-Specific Content

Display content conditionally based on Datadog site region.

```markdown
{{< site-region region="us" >}}
Configure the Agent to send data to the US site:

```yaml
site: datadoghq.com
```
{{< /site-region >}}

{{< site-region region="eu" >}}
Configure the Agent to send data to the EU site:

```yaml
site: datadoghq.eu
```
{{< /site-region >}}

{{< site-region region="gov" >}}
Configure the Agent to send data to the GovCloud site:

```yaml
site: ddog-gov.com
```
{{< /site-region >}}
```

### Code Blocks with Filename

Display code with a filename header and copy button.

```markdown
{{< code-block lang="yaml" filename="datadog.yaml" >}}
api_key: <YOUR_API_KEY>
site: datadoghq.com
logs_enabled: true
apm_config:
  enabled: true
process_config:
  process_collection:
    enabled: true
{{< /code-block >}}
```

### Collapsible Content

Create expandable sections for optional or detailed information.

```markdown
{{< collapse-content title="Advanced Configuration Options" level="h4" >}}

These advanced options are for specific use cases:

| Parameter | Description | Default |
|-----------|-------------|---------|
| `buffer_size` | Maximum buffer size in bytes | `4096` |
| `flush_interval` | Flush interval in seconds | `10` |
| `retry_count` | Number of retry attempts | `3` |

{{< /collapse-content >}}
```

### Navigation Links

Create structured navigation to related content.

```markdown
{{< whatsnext desc="Get started with these guides:" >}}
{{< nextlink href="/getting_started/agent" >}}<u>Agent</u>: Install and configure the Datadog Agent.{{< /nextlink >}}
{{< nextlink href="/getting_started/integrations" >}}<u>Integrations</u>: Collect data from your applications and infrastructure.{{< /nextlink >}}
{{< nextlink href="/getting_started/dashboards" >}}<u>Dashboards</u>: Visualize your data with custom dashboards.{{< /nextlink >}}
{{< /whatsnext >}}
```

## API Documentation

### OpenAPI Specification Structure

API documentation is generated from OpenAPI specs in `data/api/v1/full_spec.yaml` and `data/api/v2/full_spec.yaml`.

```yaml
# data/api/v2/full_spec.yaml
components:
  schemas:
    MetricPayload:
      description: The metrics payload for submission.
      properties:
        series:
          description: A list of timeseries to submit to Datadog.
          items:
            $ref: "#/components/schemas/MetricSeries"
          type: array
      required:
        - series
      type: object
    MetricSeries:
      description: A metric timeseries.
      properties:
        metric:
          description: The name of the metric.
          example: "system.cpu.user"
          type: string
        points:
          description: Points for the metric timeseries.
          items:
            $ref: "#/components/schemas/MetricPoint"
          type: array
        tags:
          description: Tags to associate with the metric.
          example: ["env:prod", "service:web"]
          items:
            type: string
          type: array
      required:
        - metric
        - points
      type: object
paths:
  /api/v2/series:
    post:
      description: Submit metrics to Datadog.
      operationId: SubmitMetrics
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MetricPayload"
        required: true
      responses:
        "202":
          description: Accepted
        "400":
          description: Bad Request
      summary: Submit metrics
      tags:
        - Metrics
```

### API Endpoint Example Pages

API endpoint pages are structured in `content/en/api/latest/<endpoint>/_index.md`.

```markdown
---
title: Metrics
---

<!-- Content is auto-generated from OpenAPI spec -->
<!-- Code examples are pulled from datadog-api-client-* repositories -->
```

## Build System

### Makefile Targets

The build system orchestrates complex build processes and external dependencies.

```bash
# Install all dependencies (Node + Python + external repos)
make dependencies

# Fetch API code examples from all language repositories
make all-examples

# Download integration data from websites-sources S3 bucket
make websites_sources_data

# Build API dereferenced specifications
make build-api-derefs

# Compile .mdoc files (Component Docs) to HTML
make build-cdocs

# Set up Python virtual environment
make hugpython

# Update pre-build content from external sources
make update_pre_build
```

### Environment Configuration

Create a `Makefile.config` file from the example template.

```makefile
# Makefile.config
GITHUB_TOKEN = your_github_personal_access_token

# Set to true for full build with all integrations
FULL_BUILD = false

# Configuration file for preview builds
CONFIGURATION_FILE = ./local/bin/py/build/configurations/pull_config_preview.yaml

# Build script source configuration
BUILD_SCRIPT_BRANCH = main
BUILD_SCRIPT_REPO_URL = https://github.com/DataDog/documentation-ci.git
BUILD_SCRIPT_SOURCE_DIR = scripts
```

### Package.json Scripts

Node.js scripts for Hugo operations and testing.

```json
{
  "scripts": {
    "prestart": "rimraf public && npx hugo mod clean",
    "start": "./node_modules/.bin/hugo server -D -d ./public -s ./ --port 1313 --poll 5s --navigateToChanged --noHTTPCache --noChmod",
    "build": "yarn run prebuild && yarn run build:hugo",
    "build:hugo": "./node_modules/.bin/hugo -d ./public -s ./ --minify --logLevel info",
    "build:preview": "GOGC=80 yarn run build:hugo -D -F --environment preview --gc",
    "build:live": "GOGC=80 yarn run build:hugo -D -F --environment live --gc",
    "jest-test": "./node_modules/.bin/jest ./assets/scripts/tests",
    "test:e2e": "npx playwright test"
  }
}
```

## Configuration Files

### Hugo Configuration

Main Hugo configuration in `config/_default/config.yaml`.

```yaml
# config/_default/config.yaml
title: "Docs"
metadataformat: "yaml"
canonifyURLs: true
pygmentsuseclasses: true
pygmentsCodeFences: true
enableRobotsTXT: true

defaultContentLanguage: "en"
defaultContentLanguageInSubdir: false

# Prevent autogeneration of jsconfig.json file
build:
  noJSConfigInAssets: true

caches:
  getjson:
    dir: :cacheDir/:project
    maxAge: '1h'

# Enable git info for sitemap lastmod
enableGitInfo: true

# Allow HTML in markdown files
markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    guessSyntax: true

# Hugo module mounts for multi-language content
module:
  mounts:
    - source: content/en
      target: content
      lang: en
    - source: content/fr
      target: content
      lang: fr
    - source: content/ja
      target: content
      lang: ja
    - source: content/ko
      target: content
      lang: ko
    - source: content/es
      target: content
      lang: es
    - source: static
      target: static
    - source: layouts
      target: layouts
    - source: data
      target: data
    - source: assets
      target: assets

timeout: 300s

minify:
  disableSVG: true
```

### Environment-Specific Parameters

Parameters configuration for different environments.

```yaml
# config/preview/params.yaml
dd_datacenter: "us"
environment: "preview"
base_url: "https://docs-staging.datadoghq.com"

# Enable draft content
show_drafts: true

# API reference configuration
api:
  version: "latest"
  base_url: "https://api.datadoghq.com"
```

## Testing and Linting

### Vale Style Linting

Run Vale linter to check documentation style compliance.

```bash
# Check a specific file
vale content/en/getting_started/_index.md

# Check all changed files
vale $(git diff --name-only HEAD~1 -- '*.md')

# Common Vale fixes:
# "once you" → "after you"
# "fine-tune" → "customize"
# "ensure" → "helps ensure"
# "leverage" → "use"
# "utilize" → "use"
```

### JavaScript Tests

Run Jest tests for JavaScript components.

```bash
# Run all JavaScript tests
yarn run jest-test

# Run specific test file
./node_modules/.bin/jest ./assets/scripts/tests/api.test.js
```

### End-to-End Tests

Run Playwright end-to-end tests.

```bash
# Run all e2e tests
yarn run test:e2e

# Run specific test
npx playwright test tests/navigation.spec.js
```

The Datadog documentation repository serves as the single source of truth for all Datadog product documentation, integrating content from multiple external sources including API client libraries, integration repositories, and the websites-sources module. Contributors can create pull requests to add or modify documentation, following the CONTRIBUTING.md style guide and using the Vale linter for consistency.

The build system supports multiple deployment environments (development, preview, live) with environment-specific configuration. The preview environment is automatically generated for pull requests, enabling documentation review before merging. The documentation is published to docs.datadoghq.com upon merging to the master branch, with automatic deployment typically completing within 35 minutes.