Data Directory Structure and YAML Variable Management in github/docs

The data directory in github/docs serves as the centralized content hub, storing YAML variables, UI strings, and feature flags that are loaded at runtime via getDataByLanguage with automatic English fallback support.

The github/docs repository powers GitHub's official documentation site, relying on a structured data architecture to separate content from presentation. The data folder acts as the single source of truth for site-wide, language-agnostic content, including glossaries, feature flags, and the YAML variables consumed by Liquid templates during the rendering pipeline.

Top-Level Directory Organization

The data directory follows a categorical structure, grouping related configuration and content into semantic subdirectories. According to the repository file list, the layout includes:

/data
├── glossaries/            # External glossary terms

│   └── candidates.yml
├── features/              # Feature-flag definitions

│   ├── dependabot.yml
│   └── copilot.yml
├── variables/             # Core YAML variable files

│   ├── actions.yml
│   ├── product.yml
│   └── rest.yml
├── ui.yml                 # UI-wide strings

├── code-languages.yml     # Code sample labels

└── survey-words.yml       # Survey phrasing

The variables/ subdirectory contains approximately 50 topical YAML files that define reusable key-value pairs across the documentation.

YAML Variable Storage Structure

Each file in data/variables/ is a standard YAML document containing dot-accessible key-value pairs. For example, data/variables/product.yml stores product-related strings:

github: GitHub
prodname_ghe_server: GitHub Enterprise Server
pricing_url: https://github.com/pricing

These keys are referenced in Liquid templates using the {% data ... %} tag syntax, such as {% data variables.product.prodname_ghe_server %}. The naming convention follows a category.key pattern that maps directly to the file structure.

Runtime Loading Mechanism

The TypeScript module src/data-directory/lib/get-data.ts handles all YAML file I/O, parsing, and localization logic. This implementation uses js-yaml for parsing and maintains an in-memory cache to ensure each file is read from disk only once per process.

The getDataByLanguage Implementation

The primary export getDataByLanguage(dottedPath, langCode) resolves variable requests through a deterministic pipeline:

1. Parses the dotted path (e.g., variables.product.github) to identify the target file
2. Constructs the file path relative to the language directory (e.g., data/variables/product.yml)
3. Invokes getYamlContent to read and parse the YAML
4. Strips Markdown front-matter using gray-matter when processing translations
5. Applies correctTranslatedContentStrings to reconcile formatting differences

import { getDataByLanguage } from '@/data-directory/lib/get-data';

// Retrieve English value for product short name
const shortName = getDataByLanguage('variables.product.company_short', 'en');
console.log(shortName); // "GitHub"

Fallback and Internationalization Rules

The loading system implements a tiered fallback strategy to ensure content availability:

• English-first fallback: When a variable is missing in the requested language, the system automatically reads from languages.en.dir before returning undefined
• Always-English overrides: Files listed in ALWAYS_ENGLISH_YAML_FILES (currently only data/variables/product.yml) are forced to English regardless of locale
• Corruption handling: If YAML parsing fails in a non-English locale, the system logs a warning and retries with the English file; English parsing errors are re-thrown to alert content writers

// Japanese request falls back to English if translation missing
const urlJa = getDataByLanguage('variables.product.pricing_url', 'ja');
// Returns English URL from product.yml

Consuming Data in Templates and Code

Variables flow through the application via two primary consumption patterns:

Liquid Template Rendering: The module src/content-render/liquid/data.ts calls getDataByLanguage to replace {% data ... %} tags during static site generation.

The product name is **{% data variables.product.prodname_ghe_server %}**.

Programmatic Link Extraction: The utility src/links/lib/extract-links.ts loads variables to resolve URL placeholders in markdown content for validation and link checking.

Summary

• The data directory in github/docs organizes site-wide content into variables/, features/, glossaries/, and standalone configuration files
• YAML variables reside in data/variables/ as topical files (e.g., product.yml, actions.yml) containing dot-notation accessible keys
• src/data-directory/lib/get-data.ts provides the core loading logic with memoization, using js-yaml for parsing and gray-matter for front-matter handling
• getDataByLanguage implements automatic English fallback and respects ALWAYS_ENGLISH_YAML_FILES for specific content that must remain untranslated
• Variables are accessible in Liquid templates via {% data variables.category.key %} and programmatically via TypeScript imports

Frequently Asked Questions

How are YAML variables referenced in markdown files?

Variables are referenced using Liquid syntax with the {% data %} tag followed by the dotted path to the variable. For example, {% data variables.product.prodname_ghe_server %} resolves to the value stored in data/variables/product.yml under the key prodname_ghe_server.

What happens if a YAML variable is not translated in a specific language?

The getDataByLanguage function automatically falls back to the English version of the file if a key is missing in the requested language. For files listed in ALWAYS_ENGLISH_YAML_FILES (such as product.yml), the system always reads from the English source regardless of the requested locale.

Where is the logic that reads YAML files located?

The core loading logic resides in src/data-directory/lib/get-data.ts. This module exports getDataByLanguage and getDataByDir, which handle file resolution, YAML parsing via js-yaml, memoization, and translation fallback logic for the entire documentation site.

Can YAML variables contain Markdown formatting?

Yes, variable values can include Markdown, though the system strips YAML front-matter from translated values using gray-matter during the loading process. The correctTranslatedContentStrings function normalizes formatting differences between translations and the English source to ensure consistent rendering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}