Skip to content

Latest commit

 

History

History
225 lines (168 loc) · 12 KB

AGENTS.md

File metadata and controls

225 lines (168 loc) · 12 KB

AGENTS.md

This file guides AI coding agents, such as Claude Code, Codex, and Cursor, when they work with code in this repository. CLAUDE.md imports this file, so make all edits here, not in CLAUDE.md.

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.

The astro/ directory contains the Astro site, which renders the live API docs (any docs with /api/ in their URL). All other docs in astro/ are in development and are not live yet.

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 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.

  • ddoghq/websites-images (https://github.com/ddoghq/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.
  • Before changing anything in the astro directory, see the astro README and agent instructions to verify that the changes are appropriate, since a contributor might try to update these files out of confusion.
  • Astro renders the API docs (any docs with /api/ in their URL), not Hugo. If you are asked to change these docs or how they render, tell the user that their PR should change the astro folder. Changes to the API docs in the hugo folder do not affect the live site. If they are Datadog employees, they can reach out for help in the #webops-platform channel on Slack.

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 context for changes, the problem you're solving, from the user's and reviewer's perspectives, NOT a detailed itemization or justification. The reviewer needs to be able to quickly understand why the changes were made. Keep it short. See PR Etiquette https://github.com/DataDog/documentation#pr-etiquette for examples.]

### Merge readiness

- [ ] Ready for merge

### AI assistance

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

### 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.

### 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. Resolve the transition ID from the issue's available transitions; IDs vary by workflow.

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

Jira cards

After opening a PR against this repo, do not create an associated Jira card on the DOCS board to prompt an editorial review. Doing so may interfere with the Docs team's own processes for creating Jira cards to track PR reviews.

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

Ask AI

Hugo's Ask AI widget has a port in shared/packages/ask-ai/, which the Astro site uses. Hugo doesn't use the package yet, so the two copies drift unless every change lands in both.

When you change Hugo's Ask AI code, make the same change in shared/packages/ask-ai/ in the same PR. Hugo's Ask AI code includes:

  • hugo/assets/scripts/components/conversational-search/
  • hugo/assets/styles/components/conversational-search/
  • hugo/layouts/partials/conversational-search.html
  • hugo/assets/scripts/tests/conversational-search-*.test.js

The package is TypeScript and builds its markup in markup.ts, so a change to Hugo's partial goes there. SCSS changes go into the package's styles.css as plain CSS on its custom properties. See the package README and AGENTS.md before editing it.

Content Types

  • Regular markdown pages
  • API reference (auto-generated). These pages are no longer published to production (that's handled in the documentation/astro folder instead) and will soon be deprecated.
  • 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.
  • Build scripts fetched from external repository during setup

Build Environments

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