Repository Directory Structure
Relevant source files
The following files were used as context for generating this wiki page:This document provides a comprehensive overview of the directory structure for the Datadog Documentation repository. This project is a static website built with Hugo and published to docs.datadoghq.com. The structure is organized to support a multi-language documentation site with a complex build system involving Hugo, Node.js, and Python.
The repository contains Markdown content, Hugo themes and layouts, build scripts, and automation tools. Understanding this structure is crucial for contributing to the documentation, running the site locally, and understanding the content generation and build processes.
High-Level Directory Overview
The repository is organized into several key top-level directories, each serving a distinct purpose in the content, presentation, and build lifecycle of the documentation site.
This diagram shows the main directories at the root of the repository.
Sources: CLAUDE.md:19-26
Key Directories
| Directory | Purpose |
|---|---|
assets/ | Contains source files like SCSS stylesheets and JavaScript that are processed by the build system. |
config/ | Holds Hugo configuration files for different environments such as development, preview, and live. |
content/ | Contains all the Markdown documentation files, organized by language. |
data/ | Stores data files (like JSON or YAML) used by Hugo to generate pages, such as API translation strings. |
layouts/ | Contains Hugo templates, including partials, shortcodes, and single-page templates that define the site's structure and appearance. |
static/ | Holds static assets like images, fonts, and other files that are copied directly to the public directory without processing. |
scripts/ | Contains build scripts, such as the Node.js script for building API pages. This directory is referenced as assets/scripts in some contexts. |
Sources: CLAUDE.md:19-26, assets/scripts/build-api-pages.js
Content Directories
The content/ directory is the heart of the documentation, housing all user-facing articles and guides in Markdown format.
Sources: CLAUDE.md:20-21
Language-Based Structure
The content is partitioned by language code, with English (en) being the primary language.
content/en/: Contains the source-of-truth English documentation. All new content and primary edits happen here.content/{fr,es,ja,ko}/: Contain translated versions of the English content. These are managed externally through a translation service and should not be edited directly in the repository.
Sources: CLAUDE.md:20-21, CONTRIBUTING.md:14-16
Content Organization
Within each language directory, content is further organized by product or feature. For example, content/en/error_tracking/ contains documentation for the Error Tracking product. Some directories, like _index.md, serve as section landing pages.
Layout and Theming
The visual presentation and structure of the site are controlled by files in the layouts, assets, and static directories.
layouts/
This directory contains all Hugo-related templates that render the Markdown content into HTML.
layouts/_default/: Contains default templates likelist.htmlandsingle.htmlfor rendering lists of pages and single pages. Thelist.search.jsonfile is a special template used to generate the search index.layouts/partials/: Contains reusable HTML snippets, such aspage-edit.html, which generates the "Edit" link on documentation pages.layouts/shortcodes/: A critical part of the repository, this directory holds a large library of custom Hugo shortcodes. These are used within Markdown to render complex components like multi-language code blocks, integration-specific assets, and API documentation. An example isintegration-assets.en.md, which defines the structure for displaying integration assets.layouts/schema/: Contains templates for specific, structured data types, like the resource catalog schema defined insingle.html.
Sources: CLAUDE.md:22, layouts/_default/list.search.json, layouts/partials/page-edit.html, layouts/shortcodes/integration-assets.en.md, layouts/schema/single.html
assets/ and static/
assets/: Contains SCSS and JavaScript files that require processing during the build. Hugo Pipes transforms these assets into production-ready CSS and JS. It also contains build scripts, for example inassets/scripts/.static/: Contains files that are served as-is, such as images (static/images/), fonts, and other resources. The path in this directory maps directly to the URL path on the live site.
Sources: CLAUDE.md:24-25, README.md:11
Build and Automation
The project uses a combination of make, Node.js, and Python scripts to automate the build process, manage dependencies, and generate content dynamically.
Sources: CLAUDE.md:28-34
Build Orchestration
The following diagram illustrates the high-level build flow.
This diagram shows that make commands orchestrate the build by calling yarn for Node.js tasks and Python scripts for fetching external content, with Hugo ultimately generating the static site.
Sources: CLAUDE.md:8-16, 36-42
API Documentation Generation
A key part of the build process is the automatic generation of API documentation from OpenAPI specification files. This is handled by the assets/scripts/build-api-pages.js script.
The process involves several steps:
- Find Spec Files: The script locates OpenAPI spec files (e.g.,
full_spec.yaml) for each API version (v1,v2). - Dereference Specs: It uses
@apidevtools/json-schema-ref-parserto resolve all$refpointers within the spec files. - Create Pages: For each API tag (e.g., "Monitors", "Dashboards"), it creates a corresponding directory and
_index.mdfile undercontent/en/api/<version>/. - Generate Resources: It processes each API endpoint to generate JSON examples for requests and responses, and HTML tables detailing the schema. These are saved into
examples.jsonandwidgets.jsonfiles within the page directory. - Update Menus: The script updates the API navigation menu (
config/_default/menus/api.en.yaml) by adding entries for each tag and operation, ensuring the side navigation is always in sync with the API specs. - Create Translations: It extracts descriptions and summaries into
translate_tags.jsonandtranslate_actions.jsonto support localization.
This diagram shows the workflow of the build-api-pages.js script.
Sources: assets/scripts/build-api-pages.js:20-47, 101-112, 428-444
Search Index Generation
The site's search functionality is powered by a JSON index generated at build time. The template layouts/_default/list.search.json is responsible for creating this index for services like Algolia or Typesense.
The process is as follows:
- Iterate Pages: The template loops through all site pages, filtering out irrelevant ones like home, API, partner pages, or drafts.
- Extract Metadata: For each valid page, it extracts the title, content, permalink, language, and other metadata from the page parameters.
- Split by Sections: The content of each page is split into sections based on
h2headings to create smaller, more relevant search records. - Generate JSON Records: A JSON object is created for each section (or the full page if no sections exist), containing a unique
objectID, title, content, and other metadata. - Output Final JSON: All individual records are aggregated into a single JSON array, which is then used to populate the search index.
Sources: layouts/_default/list.search.json:1-85
Conclusion
The documentation-datadog repository is a well-structured Hugo project designed for scalability and maintainability. Its directory structure clearly separates content, layout, configuration, and build logic. The heavy reliance on automation, particularly for generating API documentation and search indexes, allows the team to manage a large and complex documentation site efficiently. Understanding the roles of the content, layouts, and assets directories, along with the orchestration provided by Makefile and various build scripts, is essential for any contributor.