Reusables and variables

How to use, create, and choose between reusable content blocks and short string variables in GitHub Docs.

GitHub Docs manages shared content through two complementary systems: reusables for multi-sentence blocks like paragraphs and procedural steps, and variables for short strings like product names and URLs. Both are stored under data/ and inserted into content files using the {% data %} Liquid tag.

How they differ

	Reusables	Variables
Location	data/reusables/<category>/<filename>.md	data/variables/<filename>.yml
Format	Markdown file (one reusable per file)	YAML file (multiple variables per file)
Content type	Paragraphs, steps, lists, tables	Short strings, product names, URLs
Reference syntax	{% data reusables.category.filename %}	{% data variables.file.key %}

Variables

Variables are short strings stored in YAML files under data/variables/. Each file groups related variables together. The path to a variable in the {% data %} tag matches the directory path and key within the YAML file.

Referencing variables

Given the file structure:

data/
  variables/
    product.yml
    actions.yml

Variables are referenced as:

{% data variables.product.prodname_actions %}
{% data variables.product.prodname_ghe_cloud %}
{% data variables.actions.hosted_runner %}

Product name variables

The most commonly used variables are in data/variables/product.yml. Use these consistently instead of hardcoding product names — they allow for centralized updates and correct localization.

GitHub platform variables

Variable	Renders as	When to use
variables.product.github	GitHub	Generic reference to the GitHub platform.
variables.product.prodname_dotcom	GitHub	Deprecated alias for github. Prefer github.
variables.product.prodname_dotcom_the_website	GitHub.com	When the .com domain specifically matters.
variables.product.prodname_enterprise	GitHub Enterprise	Any GitHub Enterprise product.
variables.product.prodname_ghe_server	GitHub Enterprise Server	GHES specifically.
variables.product.prodname_ghe_cloud	GitHub Enterprise Cloud	GHEC specifically.

Product feature variables

Variable	Renders as
variables.product.prodname_actions	GitHub Actions
variables.product.prodname_codespaces	Codespaces
variables.product.prodname_github_codespaces	GitHub Codespaces
variables.product.prodname_copilot	GitHub Copilot
variables.product.prodname_cli	GitHub CLI
variables.product.prodname_desktop	GitHub Desktop
variables.product.prodname_pages	GitHub Pages
variables.product.prodname_registry	GitHub Packages
variables.product.prodname_GHAS	GitHub Advanced Security
variables.product.prodname_dependabot	Dependabot
variables.product.prodname_discussions	GitHub Discussions
variables.product.prodname_sponsors	GitHub Sponsors

Version-aware variables

Some variables use {% ifversion %} internally to return different strings depending on the current version context. For example:

# data/variables/product.yml
prodname_container_registry_namespace: >-
  {% ifversion fpt or ghec %}`ghcr.io`{% elsif ghes %}<code>containers.<em>HOSTNAME</em></code>{% endif %}

When referenced as {% data variables.product.prodname_container_registry_namespace %}, this renders ghcr.io on GitHub.com and a hostname-relative URL on GitHub Enterprise Server.

Creating a new variable

1. Choose or create a YAML file

   Find the relevant file in data/variables/ (for example, product.yml for product names, actions.yml for Actions-specific strings). Create a new file only if no existing file fits the category.

2. Add the key-value pair

   Add a descriptive key and its string value:

   # data/variables/product.yml
   prodname_my_new_feature: 'GitHub My New Feature'
   

   For nested variables:

   # data/variables/foo/bar.yml
   nested:
     values:
       label: 'My Label'
   

   Reference nested variables as {% data foo.bar.nested.values.label %}.

3. Reference it in content

   Use the {% data %} tag with the full dotted path:

   {% data variables.product.prodname_my_new_feature %}
   

Reusables

Reusables are longer Markdown content blocks — paragraphs, steps, tables — that appear in multiple articles. Each reusable lives in its own .md file under data/reusables/.

Referencing reusables

Given the file data/reusables/repositories/navigate-to-repo.md, reference it as:

{% data reusables.repositories.navigate-to-repo %}

The dotted path maps directly to the directory structure and filename (without the .md extension).

Real examples

Common reusables used throughout the GitHub Docs source:

{% data reusables.repositories.navigate-to-repo %}
{% data reusables.repositories.actions-tab %}
{% data reusables.actions.enterprise-github-hosted-runners %}
{% data reusables.cli.cli-learn-more %}

A reusable file can contain any valid Markdown, including Liquid conditionals:

<!-- data/reusables/repositories/about-READMEs.md -->
You can add a README file to a repository to communicate important information about your project. A README, along with a repository license{% ifversion fpt or ghec %}, contribution guidelines, and a code of conduct{% elsif ghes %} and contribution guidelines{% endif %}, communicates expectations for your project.

Reusables in ordered lists

When a reusable appears as a step inside an ordered list, use indented_data_reference with a spaces argument to preserve list indentation:

1. Navigate to your repository.
{% indented_data_reference reusables.repositories.actions-tab spaces=3 %}
1. Click **New workflow**.

The spaces value is the number of spaces the reusable lines should be indented, matching the list item indentation level.

Creating a new reusable

1. Identify the right directory

   Reusables are organized by task or product area. Look in data/reusables/ for a directory that fits your content. For example:

   • data/reusables/actions/ for GitHub Actions steps
   • data/reusables/repositories/ for repository navigation steps
   • data/reusables/organizations/ for organization management steps

   Create a new directory only if no existing directory fits.

2. Create the Markdown file

   Create a new .md file with a descriptive kebab-case name:

   data/reusables/notifications/your-reusable-name.md
   
3. Write the content

   Write valid Markdown. You can use Liquid variables and conditionals inside reusables:

   Before you begin, ensure that {% data variables.product.prodname_cli %} version 2.0 or later is installed. Run `gh --version` to check.
   
4. Reference it in content

   Add the {% data %} tag wherever the reusable should appear:

   {% data reusables.notifications.your-reusable-name %}
   

Do not edit a reusable without checking all articles that reference it. Changes affect every page that includes the reusable. Search the content/ directory for reusables.your.reusable-name before making modifications.

When to use reusables vs. variables

Use a variable

• Product names and trademarked strings
• Short UI labels that appear inline in sentences
• URLs that may change across versions
• Strings fewer than one sentence long

{% data variables.product.prodname_actions %}
{% data variables.product.prodname_ghe_cloud %}

Use a reusable

• Navigation steps repeated across multiple how-to articles
• Prerequisite paragraphs shared by related articles
• Permission statements used by multiple pages
• Any content block longer than one sentence

{% data reusables.repositories.navigate-to-repo %}
{% data reusables.cli.cli-learn-more %}

Versioning reusables and variables

Both reusables and variable values support Liquid version conditionals. This lets a single shared string serve all versions without duplicating files.

Versioned variable value

# data/variables/product.yml
login_url: >-
  {%- ifversion fpt or ghec %}
  [`https://github.com/login`](https://github.com/login)
  {%- elsif ghes %}
  `http(s)://HOSTNAME/login`
  {%- endif %}

Versioned reusable content

<!-- data/reusables/repositories/about-READMEs.md -->
You can add a README file to a repository to communicate important information about your project. A README, along with a repository license, citation file{% ifversion fpt or ghec %}, contribution guidelines, and a code of conduct{% elsif ghes %} and contribution guidelines{% endif %}, communicates expectations for your project and helps you manage contributions.

Reusables that include Liquid conditionals inherit their version context from the page that includes them — the same version the reader is currently viewing.

Directory structure reference

data/
├── variables/
│   ├── product.yml          # Product names, URLs
│   ├── actions.yml          # GitHub Actions strings
│   ├── codespaces.yml       # Codespaces strings
│   ├── copilot.yml          # Copilot strings
│   └── ...
└── reusables/
    ├── repositories/        # Repo navigation steps
    ├── actions/             # Actions-specific steps
    ├── organizations/       # Org management steps
    ├── cli/                 # CLI learn-more notes
    └── ...