Variables and shared data

Basics

Define shared variables like product names and version numbers, then use them across your documentation pages.

When values like product names, version numbers, or URLs appear on multiple pages, you can define them once in a shared file and import them wherever needed. This keeps your content consistent and makes updates easier.

Define your variables

Create a TypeScript file to hold your shared values. You can place this file anywhere under src/, but src/data/ is the recommended location:

📁 <root>
└─ 📁 src/
   ├─ 📁 content/
   │  └─ 📁 docs/
   │     ├─ 📄 getting-started.mdx
   │     └─ 📄 reference.mdx
   └─ 📁 data/
      └─ 📄 variables.ts

export const productName = 'Acme API';
export const latestVersion = '2.1.0';
export const dashboardUrl = 'https://dashboard.acme.com';

Use variables in a page

Import the variables at the top of any MDX page and reference them with curly braces:

---
title: Getting started
---
import { productName, latestVersion, dashboardUrl } from "/src/data/variables";

Welcome to Acme API! You are using version 2.1.0.
Welcome to {productName}! You are using version {latestVersion}.

Go to the [dashboard](https://dashboard.acme.com) to get your API key.
Go to the [dashboard]({dashboardUrl}) to get your API key.

The import path starts with /src/ so it resolves from the project root. Curly braces evaluate the expression inline, and variables work in both text and attribute positions.

Import all variables at once

When a page references many variables, you can use a namespace import to bring in everything with a single line:

---
title: Getting started
---
import { productName, latestVersion, dashboardUrl } from "/src/data/variables";
import * as consts from "/src/data/variables";

Welcome to {productName}! You are using version {latestVersion}.
Welcome to {consts.productName}! You are using version {consts.latestVersion}.

Go to the [dashboard]({dashboardUrl}) to get your API key.
Go to the [dashboard]({consts.dashboardUrl}) to get your API key.

The consts. prefix makes it clear where each value comes from, and you only need one import line regardless of how many variables the page uses.

Auto-import variables

If you want to skip import statements entirely, the astro-auto-import integration can make your exports available in every MDX page automatically.

Add the integration to your Astro config:

import { defineConfig } from "astro/config";
import AutoImport from "astro-auto-import";
import mdx from "@astrojs/mdx";

export default defineConfig({
  integrations: [
    AutoImport({
      imports: [
        {
          "/src/data/variables": ["productName", "latestVersion", "dashboardUrl"],
        },
      ],
    }),
    // ... other integrations
    mdx(),
  ],
});

Then use the variables directly without any import statement:

---
title: Getting started
---

Welcome to {productName}! You are using version {latestVersion}.

Go to the [dashboard]({dashboardUrl}) to get your API key.

When you have many related values, organize them into objects:

export const product = {
  name: 'Acme API',
  version: '2.1.0',
  dashboardUrl: 'https://dashboard.acme.com',
};

export const limits = {
  maxRequestsPerMinute: 1000,
  maxPayloadSize: '10 MB',
};

export const supportedLanguages = [
  { name: 'Python', slug: 'python' },
  { name: 'TypeScript', slug: 'typescript' },
  { name: 'Go', slug: 'go' },
  { name: 'Java', slug: 'java' },
];

Then reference the values with dot notation:

---
title: API reference
---
import { product, limits } from "/src/data/variables";

# Acme API reference
# {product.name} reference

The current version is 2.1.0.
The current version is {product.version}.

## Rate limits

You can make up to 1000 requests per minute.
You can make up to {limits.maxRequestsPerMinute} requests per minute.
The maximum payload size is 10 MB.
The maximum payload size is {limits.maxPayloadSize}.

Objects are useful when you have many related values that belong to the same concept, such as product metadata or API limits.

Render lists from arrays

You can export arrays and map over them to render dynamic lists or tables:

---
title: Supported languages
---
import { supportedLanguages } from "/src/data/variables";

We generate SDKs for the following languages:

<ul>
  {supportedLanguages.map((lang) => (
    <li key={lang.slug}>
      <a href={`/docs/sdks/${lang.slug}`}>{lang.name}</a>
    </li>
  ))}
</ul>

Because MDX expressions are standard JavaScript, you can use .map(), .filter(), and other array methods to transform your data into rendered content. Wrap the output in HTML elements like <ul> or <table> to control the structure.

Reuse content blocks with partials

Variables are ideal for individual values such as names, numbers, and URLs. When you need to reuse entire blocks of content, including paragraphs, tables, or sections, use Markdown partials instead.

Partials let you write content once in a separate file and render it on multiple pages. See the Markdown partials guide for details.

Variables and shared data

Define your variables

Use variables in a page

Import all variables at once

Auto-import variables

Group related variables

Render lists from arrays

Reuse content blocks with partials