Skip to main content
MDX upload is the second path for creating a Horizon. You author the Horizon as an .mdx file in any editor (a Markdown editor, VS Code, the studio’s preferred environment) and upload the file to Brand Atlas. MDX upload is available on every tier that supports Horizons.

​
When to choose MDX upload

MDX upload is the right path when:
  • You are already comfortable writing in Markdown or MDX.
  • A studio or external collaborator is authoring the Horizon on your behalf and wants to deliver a file rather than work in the portal.
  • The Horizon contains code samples, technical specifications, or other content that authoring as a file is easier for than building block-by-block.
  • You want to keep the Horizon under version control outside Brand Atlas before publishing.
The visual editor is faster for most one-off Horizons. MDX upload is faster for technically-authored ones and for repeat authoring across multiple atlases.

​
The MDX format

A Brand Atlas Horizon is a standard MDX file: Markdown plus a small set of Mintlify-compatible MDX components. Frontmatter at the top sets the Horizon’s metadata; the body is the content. 
---
title: "Spring 2026 Campaign"
description: "Visual and verbal system for the Spring 2026 launch campaign."
horizonType: "campaign"
audience: "all-team-members"
expires: "2026-08-31"
---

## What this campaign is

Brief text describing the campaign...

## The visual system

<Frame>
  <img src="./assets/spring-2026-hero.jpg" alt="Spring 2026 campaign hero image." />
</Frame>

## The typographic treatment

<Tabs>
  <Tab title="Headlines">
    Caslon Italic at 96/100, tracked 0.
  </Tab>
  <Tab title="Body">
    Inter Regular at 18/28, tracked 0.
  </Tab>
</Tabs>
Frontmatter fields:
  • title (required). The Horizon’s display name.
  • description (required). One sentence, ≤160 characters.
  • horizonType (optional). One of sub-brand, campaign, regional, partnership, internal, product. Used for sidebar grouping.
  • audience (optional). One of all-team-members, editors-only, specific-people. Specific people are configured in the portal after upload.
  • expires (optional). An ISO date. After this date, the Horizon is automatically archived. Useful for campaigns.

​
Supported components

The MDX format supports the same components as the visual editor exposes, plus a few that are only available through MDX:
  • <Frame> — wrap an image.
  • <Tabs> and <Tab> — switch between parallel content.
  • <Steps> and <Step> — ordered procedure.
  • <AccordionGroup> and <Accordion> — collapsible blocks.
  • <CardGroup> and <Card> — routing cards.
  • <Note>, <Tip>, <Info>, <Warning>, <Check> — callouts.
  • <Code> and <CodeGroup> — code blocks and multi-language sets.
Custom React components are not supported in uploads. The renderer accepts a fixed component set.

​
Uploading the file

1

Open Horizons

From Horizons → New Horizon, choose MDX upload.
2

Upload the .mdx file

Drag the file into the upload area or select it from disk. If the Horizon references external image files, upload the image files in the same operation. Relative paths in the MDX (./assets/...) are resolved against the uploaded files.
3

Review the preview

Brand Atlas renders the uploaded Horizon as a preview. Check the rendering matches your expectation. If the preview shows errors, the MDX has syntax issues; fix the file and re-upload.
4

Publish

From the preview, click Publish. The Horizon is added to the active list and visible to its audience.
The MDX-authored Horizon is live. You can edit later through the visual editor, by re-uploading a new MDX file, or both.

​
Editing an MDX-authored Horizon

After upload, an MDX Horizon can be edited in two ways:
  • Through the visual editor. Edits are made in the portal; the resulting state replaces the uploaded version.
  • Through re-upload. A new .mdx file replaces the current state. Useful for keeping the Horizon under external version control.
Mixing the two is supported but produces conflicting source-of-truth questions. Choose one path per Horizon.

​
Multi-Horizon uploads

To upload several Horizons at once, package them as a ZIP file with this layout: 
my-horizons.zip
├── manifest.json
├── horizons/
│   ├── spring-2026-campaign.mdx
│   ├── arabic-typography.mdx
│   └── partner-acme.mdx
└── assets/
    ├── spring-2026-hero.jpg
    └── partner-acme-lockup.svg
manifest.json lists the Horizons and any per-Horizon overrides. Multi-Horizon uploads count against the tier limit at upload time.

​
Validation

The portal validates the MDX on upload:
  • Syntax. MDX must parse.
  • Frontmatter. Required fields must be present.
  • Components. Only the supported component set is accepted.
  • References. Asset references must resolve.
  • Size. Files larger than 10MB are flagged for review.
Validation errors are listed before the upload is accepted; nothing is published until the errors are resolved.

Visual editor

The alternative authoring path.

Templates and patterns

Starter templates.

Authoring in MDX

The full MDX reference.