DataDog/documentation: the Hugo source behind the Datadog docs site

A Hugo build of markdown, not a documentation application

The repository is the source of the Datadog documentation site, and the mechanism is deliberately boring: the markdown stored here is published to docs.datadoghq.com using Hugo, a static website generation tool. Everything the site serves is a file in the repository, rendered by the Hugo build. There is no content database to request an API key for and no CMS to be granted access to, which is what makes the contribution path open to anyone. The tooling around the build matches the shape of the project. The top level carries a hugo directory for the site, a shared directory for content reused across pages, a Vale configuration for prose linting, a Prettier configuration with its own ignore file, ESLint configuration, a RuboCop configuration for any Ruby scripts in the tree, Husky for git hooks, and Docker Compose files for local development. There is also a translate.yaml, which points to a translation workflow, and repository.datadog.yml alongside other configuration files that describe the repository to Datadog's own tooling.

Every page carries an Edit button that opens a pull request

The feature that separates this from a typical vendor documentation site is the link between the rendered page and the repository. Most pages on the documentation site feature an Edit button that sends the reader to the source file in the repository, and the reader can make the edit directly on the GitHub website. The distance between noticing a mistake and fixing it is therefore one click and one commit, without a support ticket and without needing write access, since the edit happens through a fork and a pull request. The Documentation team is added as a PR reviewer automatically, so a submitted change reaches a human without anyone having to find the right person. The contribution guidelines and the build setup guide are linked from the project for anyone who wants the longer version of these instructions, and there is a dedicated doc page explaining how to add a new integration.

One problem per pull request, with a description written by a human

The contribution guidance is unusually specific, which tells you what the review bottleneck is. A pull request should address one problem, maybe two, not many, although it can touch many files in addressing that one problem. If a pull request is getting very large, the guidance is to reach out and ask how it should be structured. The description is where the guidance is sharpest: it should be written by you, the human, not AI, and it should be concise and focused on the problem solved with the change and the context for opening it, rather than an itemisation of the changes, which is already visible on the Changes tab. The listed good descriptions are short and specific, for example noticing something was wrong or missing, or updating the docs to reflect code changes or new defaults, and the bad ones include a detailed account of the customer who reported the problem and unfiltered AI output written from the assistant's own perspective.

AI-generated content is accepted, human review is not optional

The stance on AI tooling is probably the most quotable part of the guide, and it is a position rather than a ban. The docs team are described as large fans of AI tools such as Claude Code, and they use them to generate content all the time. The qualification is what follows: they will always rely on human review to ensure that published content meets the standard they set, and a large AI-generated pull request takes time for them to think through how people take in and use the information. The practical advice is to validate the content independently before submitting and to plan timelines accordingly, so the pull request gets the attention it deserves. For a contributor this means an AI-written page is fine as a starting point but weak on its own, since the review cost lands on the team, and the same guidance is why the description has to be written by you rather than pasted.

A branch name decides whether CI and the preview site run

The two contributor paths differ in one consequential detail. Outside contributors fork the master branch, commit, and open a pull request back to DataDog/master. Datadog staff must branch off master rather than fork, must not commit directly to master, and must name the branch with the format <name>/<description>. The documentation is blunt about the consequence: if you omit the forward slash, the GitLab pipeline does not run, there is no branch preview, and the pull request will not pass in CI. Getting a branch preview matters because it lets the team check the change, including broken links, before merging. A named branch also produces build notifications in Slack, using a Slack username in the branch name. Staff should also use draft pull requests with labels such as Do Not Merge or Work in Progress until the change is ready to go live, and if the branch is named correctly a bot posts a link to the preview website for that pull request once the preview build finishes.

Goldmark, CommonMark 0.29 and lowercase file names

Two content rules catch people out. The site renders markdown with Goldmark, which is compliant with CommonMark 0.29, and the instruction is blunt: if you include any markdown in a file, which covers 99.9 percent of cases, give it a .md extension. The second rule concerns file names, which must all be lowercase. The reason is a mismatch between developer machines and the build server: macOS is case-insensitive when creating links to images and pages, but the build server is not, so a link that works locally can still fail in production. That is a class of bug that only appears after merge, and the lowercase convention removes it. Running the build locally is optional, since a correctly named branch produces a preview automatically, but the repository does document a local build through the build setup guide and links a Docker based development path and an example Makefile configuration for people who prefer to work that way.

Deploys start within ten minutes and finish around thirty-five

The release process is one step: merging to master triggers an automatic deployment. The documentation gives the timing, and it is unusually candid for a deployment note. The process typically begins within 10 minutes and usually takes around 35 minutes to complete, though those times may vary. For a contributor that means a fix is not live the moment it merges, and a second change landing in the same window may land in the same deployment or the next one, depending on where the cut falls. The maintenance picture of the repository itself is worth noting too. The only tag is master3895, a manual tag from 2021-02-10, so the release list tells you nothing about the current state of the site. The repository is not archived, the last push was on 2026-10-22, and there is a REPO_REORG.md at the top level describing a reorganisation of the repository. The licence is also unusual: it is a custom licence that GitHub cannot classify, and the LICENSE file is the place to read the actual terms.

Editorial conclusion

Adopt this repository if you want to correct a Datadog documentation page, since the Edit button and the contribution path are documented end to end. Do not treat it as a software dependency or a mirror of the product source, and read the branch naming rule before your first pull request, because a branch without a slash never reaches CI or the preview site.

Frequently asked questions

Official sources

1. DataDog/documentation on GitHub
2. Issues
3. Project website
4. README
5. Releases