# Data Directory Structure and YAML Variable Management in github/docs

> Explore the github/docs data directory structure and learn how YAML variables, UI strings, and feature flags are managed. Understand content loading with automatic English fallback.

- Repository: [GitHub/docs](https://github.com/github/docs)
- Tags: internals
- Published: 2026-06-01

---

**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:

```text
/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`](https://github.com/github/docs/blob/main/data/variables/product.yml) stores product-related strings:

```yaml
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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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

```typescript
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`](https://github.com/github/docs/blob/main/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

```typescript
// 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`](https://github.com/github/docs/blob/main/src/content-render/liquid/data.ts) calls `getDataByLanguage` to replace `{% data ... %}` tags during static site generation.

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

```

**Programmatic Link Extraction**: The utility [`src/links/lib/extract-links.ts`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/product.yml), [`actions.yml`](https://github.com/github/docs/blob/main/actions.yml)) containing dot-notation accessible keys
- **[`src/data-directory/lib/get-data.ts`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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.