Skip to content

CLAUDE.md

Latest commit

 

History

History
208 lines (157 loc) · 9.8 KB

CLAUDE.md

File metadata and controls

208 lines (157 loc) · 9.8 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the Datadog Documentation repository, built using Hugo (static site generator) and published to docs.datadoghq.com. The codebase consists of markdown content, Hugo themes, Node.js build scripts, and Python automation tools.

The repository is a monorepo that supports more than one site. All Hugo site files live in the hugo/ directory, not at the repository root. Paths in this document are relative to the repository root unless noted otherwise. For background, see REPO_REORG.md.

Development Commands

Run all build and development commands from the hugo/ directory. There is no package.json or Makefile at the repository root.

Build and Development

  • yarn start or make start - Full build including external dependencies and run development server
  • yarn run start - Basic Hugo development server (port 1313)
  • make start-no-pre-build - Skip external dependencies, build and run
  • make start-preserve-build - Keep existing build scripts for local testing
  • make start-docker - Build and run via Docker container

Build Commands

  • yarn build or make build - Production build
  • yarn run build:hugo - Run Hugo build only
  • yarn run build:preview - Build with preview environment
  • make build-cdocs - Compile .mdoc files to HTML

Testing and Quality

  • yarn run jest-test - Run JavaScript tests
  • make clean - Clean generated files
  • make clean-all - Clean everything (environment, repos, generated files)

Dependencies

  • yarn install - Install Node.js dependencies
  • make dependencies - Install all dependencies (Node + Python + external repos)
  • make hugpython - Set up Python virtual environment

Architecture

Content Structure

  • hugo/content/en/ - English documentation (primary language)
  • hugo/content/{fr,es,ja,ko}/ - Translated content (managed externally)
  • hugo/layouts/ - Hugo templates and shortcodes
  • hugo/static/ - Static assets, images, fonts
  • hugo/assets/ - SCSS stylesheets and JavaScript

Build System

  • Hugo: Static site generator with custom themes
  • Node.js: Package management, build automation, asset processing
  • Python: Content processing, integration data fetching, translations
  • Makefile: Orchestrates complex build processes and external dependencies

External Dependencies

The build system automatically fetches:

  • API client examples from multiple language repositories
  • Integration metadata and documentation
  • Vector integration data via CUE files
  • Some documentation is sourced from GitHub using the pull_config.yaml file at hugo/local/bin/py/build/configurations/pull_config.yaml.
  • Some documentation is sourced from a go module called websites-sources

Related Repositories

These repositories are dependencies of or closely related to this project. They may be cloned as siblings of this repo in the same parent directory:

  • DataDog/documentation-ci (https://github.com/DataDog/documentation-ci) — GitLab CI configuration for this repo. Contains documentation-gitlab-config.yml, which defines all CI jobs, the Docker build image URL (FF_BUILD_IMAGE_URL), GitHub token setup via dd-octo-sts, and trust policies. Changes here affect pipeline behavior for all branches.

  • DataDog/websites-images (https://github.com/DataDog/websites-images) — Builds the Docker image used by CI (webops-site-build). When a PR merges here, a new image is published and the image tag in documentation-ci must be bumped to pick it up. CI failures related to the build environment (network issues, missing tools, broken scripts baked into the image) often trace back here.

  • DataDog/websites-sources (https://github.com/DataDog/websites-sources) — Provides integration data consumed during the build via S3. The make websites_sources_data target downloads this data. The S3 path is controlled by the FF_S3_PATH env var (default: staging).

Configuration

  • hugo/config/ - Hugo configuration for different environments (development, preview, live)
  • hugo/package.json - Node.js dependencies and scripts
  • hugo/Makefile + hugo/Makefile.config - Build orchestration
  • Environment-specific parameters in hugo/config/{env}/params.yaml

Critical Rules

  • NEVER push directly to master. Always create a PR and go through the review process. Direct pushes bypass branch protection and code review.
  • Obey the git hooks set up in .husky. Do not use --no-verify or other workarounds to skip repository git hooks.
  • NEVER force-push any branch. Do not use git push --force, git push -f, or --force-with-lease. Force-pushing rewrites history and destroys commit history in open PRs.
  • The rules above are enforced mechanically. A PreToolUse hook (.claude/hooks/block-master-git.py) blocks commits and pushes that target master, along with --no-verify, HUSKY=0, and force-push flags. The .husky git hooks enforce the same rules for commits made outside Claude Code. A block from either layer is intentional. Do not work around it.
  • This is a PUBLIC repository. NEVER include internal or sensitive information in documentation content, commit messages, PR titles, PR descriptions, or code comments. This includes: customer names, incident details (Sev 1s, outages, etc.), internal URLs, internal Slack conversations, Jira ticket details beyond the ticket key, internal bugs or implementation details, or any context that isn't appropriate for public visibility. Documentation should describe how to use features, not reference internal issues (e.g., not "there's currently a bug in the backend that processes this"). PR descriptions should describe what changed in the docs, not why internally (e.g., not "a customer hit a Sev 1 because..."). Keep all content concise and focused on the user-facing documentation change itself.

Branch and PR Guidelines

Branch Naming

CRITICAL: Always use format <name>/<description> with forward slash. Without this:

  • GitLab pipeline won't run
  • No branch preview will be generated
  • CI will fail

PR Checklist

  • Leave the "Ready for merge" checkbox unchecked unless explicitly requested.

PR Title Format

Use the Jira ticket key in square brackets: [DOCS-XXXXX] Brief description

PR Description Template

<!-- *Note: Please remember to review the Datadog Documentation [Contribution Guidelines](https://github.com/DataDog/documentation/blob/master/CONTRIBUTING.md) if you have not yet done so.* -->
### What does this PR do? What is the motivation?

Fixes DOCS-XXXXX

[Brief description of changes]

### Merge readiness

- [ ] Ready for merge

## For Datadog employees:

- ⚠️ Your branch name **MUST** follow the `<name>/<description>` convention and include the forward slash (`/`). If you've already created your PR with an incorrect branch name, please rename your branch and open a fresh PR.
- 🤖 **New**: Comment with `/review` to run an automated check that catches common issues before a Documentation team member reviews your PR.

### AI assistance

[If AI tools were used, briefly note how. Leave blank if not applicable.]

### Additional notes

Pre-commit Checklist

Before committing changes, run Vale to check style compliance:

vale /path/to/changed/file.md

Fix any warnings before committing. Common issues:

  • "once you" → "after you"
  • "fine-tune" → "customize"
  • "ensure" → "helps ensure"
  • Remove filler words: easy, simple, just, please, very

Commit Messages

  • Keep messages concise and descriptive

Jira Workflow

  • When a PR is created, transition the Jira ticket to Reviewable status (transition ID: 101)

Content Guidelines

Follow the CONTRIBUTING.md style guide:

  • Use American English (en_US)
  • Be plain, direct, and concise
  • Provide explicit instructions with examples
  • Use imperative voice for instructions
  • Don't edit translated content directly (managed externally)

Style Rules (from datadog-vale)

The full Vale linter rules are at https://github.com/DataDog/datadog-vale. Key substitutions:

Don't use Use instead
once you/once the after you/after the
fine-tune customize, optimize, or refine
ensure/ensures helps, helps ensure
leverage use, apply, take advantage of
utilize use
in order to to
easy/easily (remove)
simple/simply (remove)
just (remove)
please (remove)
via with, through
Note that Note:
drill down/into examine, investigate, analyze
refer to/visit see, read, follow
obvious/obviously (remove)
seamless/seamlessly (remove)
quick/quickly (remove)

Avoid temporal words: currently, now, will, won't

Hugo-Specific Details

Shortcodes

Extensive library in hugo/layouts/shortcodes/ for:

  • Code examples across multiple languages
  • Integration-specific content
  • API documentation
  • Security and compliance sections

Content Types

  • Regular markdown pages
  • API reference (auto-generated)
  • Integration pages (auto-populated from external repos)
  • Multi-language code examples

Development Notes

Local Development

  • Requires Node.js >= 20.11.0
  • Python 3 for build scripts
  • Uses Yarn package manager (v3.6.1)
  • Development server runs on port 1313

External Content

  • API examples automatically sync from datadog-api-client-* repositories
  • Integration data pulled from the websites-sources go module.
    • The exception is Dogweb integrations, which are pulled from a GitHub repository.
  • Some documentation is sourced from GitHub using the pull_config.yaml file at hugo/local/bin/py/build/configurations/pull_config.yaml.
  • Build scripts fetched from external repository during setup

Build Environments

  • Development: Local development with drafts
  • Preview: Branch previews for PRs
  • Live: Production deployment