# Managing Reusables and Includes in GitHub Docs: Content Architecture Patterns

> Discover content architecture patterns for managing reusables and includes in GitHub Docs. Learn how GitHub Docs uses Liquid and TypeScript for efficient Markdown fragment management.

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

---

**GitHub Docs stores reusable Markdown fragments and configuration variables under a centralized `data/` directory, embedding them into content at render time using Liquid data tags parsed by TypeScript handlers.**

Managing reusables and includes in the `github/docs` repository requires a systematic approach to content reuse across thousands of localized pages. The architecture relies on dotted-path references that map to specific files within the `data/` directory tree, enabling content authors to maintain single sources of truth for repetitive text snippets. This system supports automatic language fallback, conditional rendering based on feature flags, and indentation preservation for nested contexts.

## Core Liquid Tag Patterns

The repository implements four primary Liquid tag patterns for content inclusion, each handled by specific parser modules in the `src/content-render/` directory.

### The Data Tag Pattern

The `{% data reusables.<dotted-path> %}` tag inserts Markdown files located at `data/reusables/<dotted-path>.md`. The parser in [`src/content-render/liquid/data.ts`](https://github.com/github/docs/blob/main/src/content-render/liquid/data.ts) processes these tags by converting the dot notation into a file system path (e.g., `reusables.webhooks.action_type_desc` becomes [`data/reusables/webhooks/action_type_desc.md`](https://github.com/github/docs/blob/main/data/reusables/webhooks/action_type_desc.md)).

```liquid
{% data reusables.webhooks.action_type_desc %}

```

### Indented Data References

For content nested within lists or tables, `{% indented_data_reference reusables.<path> spaces=<n> %}` preserves original indentation. This pattern is processed by [`src/content-render/liquid/indented-data-reference.ts`](https://github.com/github/docs/blob/main/src/content-render/liquid/indented-data-reference.ts), ensuring that nested Markdown maintains proper structure when injected into parent documents.

```liquid
- Steps to enable two-factor authentication:
  {% indented_data_reference reusables.two_fa.2fa_not_supported_with_saml_and_cas spaces=2 %}

```

### Variable Injection

Scalar values stored in YAML or JSON files under `data/variables/` are accessed via `{% data variables.<dotted-path> %}`. This pattern retrieves single values rather than Markdown fragments, useful for product names or configuration strings that change across versions.

```liquid
{% data variables.product.prodname_ghe_server %}

```

### Conditional Rendering with Feature Flags

Version-specific content uses `{% ifversion <feature> %}` tags that reference definitions stored in `data/features/*.yml`. The system evaluates these flags during the render pipeline to include or exclude content blocks based on the current feature set.

```liquid
{% ifversion actions %}
  See the [GitHub Actions](/actions) documentation for more details.
{% endif %}

```

## Resolution Flow and Architecture

The render pipeline follows a strict resolution sequence implemented in [`src/data-directory/lib/get-data.ts`](https://github.com/github/docs/blob/main/src/data-directory/lib/get-data.ts). When the Liquid parser encounters a data tag, it invokes **`getDataByLanguage`** with the dotted path and current language code.

The function translates the dotted notation into a physical file location within the `data/` directory. If a localized version does not exist for the requested language, the system automatically falls back to the English source file. This resolution occurs at render time, ensuring that the final HTML contains fully resolved content rather than template references.

Key files in this pipeline include:

- [`src/content-render/liquid/data.ts`](https://github.com/github/docs/blob/main/src/content-render/liquid/data.ts) — Handles standard `{% data %}` tag resolution
- [`src/content-render/liquid/indented-data-reference.ts`](https://github.com/github/docs/blob/main/src/content-render/liquid/indented-data-reference.ts) — Manages indentation-preserving references
- [`src/data-directory/lib/get-data.ts`](https://github.com/github/docs/blob/main/src/data-directory/lib/get-data.ts) — Core API for all data lookups and language fallback logic

## Management Tooling and Validation

The repository includes specialized tooling to prevent orphaned reusables and validate references. The **Reusables CLI** ([`src/content-render/scripts/reusables-cli/README.md`](https://github.com/github/docs/blob/main/src/content-render/scripts/reusables-cli/README.md)) provides maintenance commands for content governance:

```bash
npm run reusables -- find unused
npm run reusables -- find top-used

```

Linting rules in [`src/content-linter/lib/linting-rules/liquid-data-tags.ts`](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/liquid-data-tags.ts) validate that referenced reusables exist and are not corrupted. The test suite in [`src/content-linter/tests/site-data-references.ts`](https://github.com/github/docs/blob/main/src/content-linter/tests/site-data-references.ts) ensures that `{% ifversion %}` tags reference defined features in the `data/features/` directory, preventing runtime errors in conditional content.

## Practical Implementation Examples

Content authors implement these patterns by storing reusable fragments in `data/reusables/` as Markdown files and variables in `data/variables/` as YAML or JSON. The following example demonstrates combining conditional logic with reusable content:

```liquid
{% ifversion actions %}
  {% data reusables.webhooks.action_type_desc %}
  Contact {% data variables.product.prodname_support %} for assistance.
{% endif %}

```

For nested documentation structures requiring indentation preservation, use the indented reference pattern:

```liquid
1. Configure the application:
   {% indented_data_reference reusables.enterprise.configuration_note spaces=3 %}
2. Verify the installation.

```

## Summary

- **GitHub Docs** manages reusables and includes through a centralized `data/` directory architecture that separates content from presentation.
- **Liquid data tags** (`{% data %}`, `{% indented_data_reference %}`) resolve at render time via TypeScript handlers in `src/content-render/liquid/`.
- **Automatic fallback** to English occurs when localized reusable versions are missing, handled by `getDataByLanguage` in [`src/data-directory/lib/get-data.ts`](https://github.com/github/docs/blob/main/src/data-directory/lib/get-data.ts).
- **Feature flags** in `data/features/*.yml` enable conditional content rendering through `{% ifversion %}` tags.
- **Validation tooling** includes the Reusables CLI for maintenance and linter rules in `src/content-linter/` to ensure reference integrity.

## Frequently Asked Questions

### How does GitHub Docs handle missing translations for reusable content?

When a localized version of a reusable does not exist in the `data/` directory, the system automatically falls back to the English source file. This behavior is implemented in [`src/data-directory/lib/get-data.ts`](https://github.com/github/docs/blob/main/src/data-directory/lib/get-data.ts) through the `getDataByLanguage` function, ensuring that content rendering never fails due to incomplete translations.

### What is the difference between `{% data %}` and `{% indented_data_reference %}` tags?

The `{% data %}` tag inserts reusable content at the current indentation level, while `{% indented_data_reference %}` preserves the original indentation of the source Markdown using a `spaces=<n>` parameter. The latter is essential for nested list items or table cells where indentation affects Markdown parsing, and is processed separately in [`src/content-render/liquid/indented-data-reference.ts`](https://github.com/github/docs/blob/main/src/content-render/liquid/indented-data-reference.ts).

### Where are feature flags defined for conditional content rendering?

Feature flags are defined in YAML files located under `data/features/*.yml`. These definitions are validated by tests in [`src/content-linter/tests/site-data-references.ts`](https://github.com/github/docs/blob/main/src/content-linter/tests/site-data-references.ts) to ensure that all `{% ifversion %}` tags reference existing features. The system evaluates these flags during the render pipeline to conditionally include or exclude content blocks.

### How can content teams identify unused reusables in the repository?

Content teams use the Reusables CLI tool documented in [`src/content-render/scripts/reusables-cli/README.md`](https://github.com/github/docs/blob/main/src/content-render/scripts/reusables-cli/README.md). Running `npm run reusables -- find unused` scans the codebase to identify Markdown files in `data/reusables/` that are not referenced by any Liquid tags, enabling cleanup of obsolete content fragments.