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.
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.
Run all build and development commands from the hugo/ directory. There is no package.json or Makefile at the repository root.
yarn startormake start- Full build including external dependencies and run development serveryarn run start- Basic Hugo development server (port 1313)make start-no-pre-build- Skip external dependencies, build and runmake start-preserve-build- Keep existing build scripts for local testingmake start-docker- Build and run via Docker container
yarn buildormake build- Production buildyarn run build:hugo- Run Hugo build onlyyarn run build:preview- Build with preview environmentmake build-cdocs- Compile .mdoc files to HTML
yarn run jest-test- Run JavaScript testsmake clean- Clean generated filesmake clean-all- Clean everything (environment, repos, generated files)
yarn install- Install Node.js dependenciesmake dependencies- Install all dependencies (Node + Python + external repos)make hugpython- Set up Python virtual environment
hugo/content/en/- English documentation (primary language)hugo/content/{fr,es,ja,ko}/- Translated content (managed externally)hugo/layouts/- Hugo templates and shortcodeshugo/static/- Static assets, images, fontshugo/assets/- SCSS stylesheets and JavaScript
- 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
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
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. Containsdocumentation-gitlab-config.yml, which defines all CI jobs, the Docker build image URL (FF_BUILD_IMAGE_URL), GitHub token setup viadd-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 indocumentation-cimust 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. Themake websites_sources_datatarget downloads this data. The S3 path is controlled by theFF_S3_PATHenv var (default:staging).
hugo/config/- Hugo configuration for different environments (development, preview, live)hugo/package.json- Node.js dependencies and scriptshugo/Makefile+hugo/Makefile.config- Build orchestration- Environment-specific parameters in
hugo/config/{env}/params.yaml
- 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-verifyor 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
PreToolUsehook (.claude/hooks/block-master-git.py) blocks commits and pushes that targetmaster, along with--no-verify,HUSKY=0, and force-push flags. The.huskygit 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
astrodirectory, see theastroREADME 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 theastrofolder. Changes to the API docs in thehugofolder do not affect the live site. If they are Datadog employees, they can reach out for help in the #webops-platform channel on Slack.
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
- Leave the "Ready for merge" checkbox unchecked unless explicitly requested.
Use the Jira ticket key in square brackets: [DOCS-XXXXX] Brief description
<!-- *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
Before committing changes, run Vale to check style compliance:
vale /path/to/changed/file.mdFix any warnings before committing. Common issues:
- "once you" → "after you"
- "fine-tune" → "customize"
- "ensure" → "helps ensure"
- Remove filler words: easy, simple, just, please, very
- Keep messages concise and descriptive
- 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.
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)
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
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.
Extensive library in hugo/layouts/shortcodes/ for:
- Code examples across multiple languages
- Integration-specific content
- API documentation
- Security and compliance sections
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.htmlhugo/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.
- Regular markdown pages
- API reference (auto-generated). These pages are no longer published to production (that's handled in the
documentation/astrofolder instead) and will soon be deprecated. - Integration pages (auto-populated from external repos)
- Multi-language code examples
- Requires Node.js >= 20.11.0
- Python 3 for build scripts
- Uses Yarn package manager (v3.6.1)
- Development server runs on port 1313
- API examples automatically sync from datadog-api-client-* repositories
- Integration data pulled from the
websites-sourcesgo module.- The exception is Dogweb integrations, which are pulled from a GitHub repository.
- Build scripts fetched from external repository during setup
- Development: Local development with drafts
- Preview: Branch previews for PRs
- Live: Production deployment