Managing Reusables and Includes in GitHub Docs: Content Architecture Patterns

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 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).

{% 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, ensuring that nested Markdown maintains proper structure when injected into parent documents.

- 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.

{% 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.

{% 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. 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 — Handles standard {% data %} tag resolution
• src/content-render/liquid/indented-data-reference.ts — Manages indentation-preserving references
• 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) provides maintenance commands for content governance:

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

Linting rules in 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 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:

{% 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:

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.
• 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 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.

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 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. 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.

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