Media

Add images, SVG icon specimens, and downloadable files to authored pages.

Use imported files for responsive image specimens and public/ for files that need a predictable URL. Keep media in your consumer project; .brandtree/ is generated output. Register shared logo artwork and download metadata once in Brand assets, then use them in your content.

File locations

Imported images participate in Astro’s image pipeline. Public files are served unchanged. An import path is relative to the MDX file, while a root-relative URL starts at the site’s public root. Include your configured basePath in root-relative links when hosting below a path.

Imported photographs and mockups

Imports resolve relative to the MDX file. For content/02-photography.mdx, a photograph in assets/photography/ uses ../assets/. For content/en/02-photography.mdx, it uses ../../assets/.

---
title: Photography
---

import team from "../assets/photography/team.jpg";

<Figure
  src={team}
  alt="The Acme team reviewing printed layouts around a table"
  caption="Show people doing real work."
  ratio="3 / 2"
/>

The generated MDX runtime supplies built-in components such as Figure and PhotoGrid and automatically supplies their shared props. An imported image lets Figure use Astro’s responsive image pipeline. Figure also accepts a public URL string, which renders a regular image:

<Figure
  src="/brand/storefront.jpg"
  alt="Acme's wordmark above the store entrance"
  fit="contain"
/>

Use fit="contain" to show an entire mockup or mark; the default cover fills and crops the frame. A Figure without src renders a placeholder, useful while artwork is being prepared. Replace intentional draft placeholders before publishing final guidance.

Photography grids

PhotoGrid expects imported image metadata, not URL strings:

import team from "../assets/photography/team.jpg";
import workshop from "../assets/photography/workshop.jpg";

<PhotoGrid
  images={[
    { src: team, caption: "People collaborating in natural light" },
    { src: workshop, caption: "Close details of the making process" },
  ]}
  cols={2}
  ratio="4 / 3"
  treatment="none"
/>

It also accepts bare imports (images={[team, workshop]}), but those render with empty image alternatives. Supply wrapper objects with meaningful caption values when the image conveys information: the caption is also used as its alt text. Optional span controls an item’s column span. Treatments are none, mono, and duotone; duotone uses the brand’s primary color.

Avoid putting full-page prose into captions. Write the photographic principles as MDX paragraphs beside the examples, keeping the shared images reusable across locales. See Pages and MDX for MDX structure and components for the complete component surface.

Brand icon specimens

IconGrid displays an explicit array of names and raw SVG strings. It does not automatically scan an icon directory. Create a module such as assets/icons/index.ts:

import arrow from "./arrow.svg?raw";
import document from "./document.svg?raw";

export const icons = [
  { name: "arrow", svg: arrow },
  { name: "document", svg: document },
];

Then import it into a content page:

import { icons } from "../assets/icons/index.ts";

<IconGrid icons={icons} unit={24} version="v1.0" cols={4} />

<IconGrid icons={icons} only={["document", "arrow"]} />

Without only, icons are sorted by name. only selects and orders items; an unknown requested name throws an error. unit describes the drawing grid shown on the first tile. Include a suitable SVG viewBox; use currentColor for strokes or fills that should follow the page foreground.

Raw SVG is inserted into the document as markup, so use artwork you maintain or trust. This is separate from navigation icons: page and folder metadata accept names from the bundled Phosphor Iconify collection, with bare names or a ph: prefix. Adding an SVG to IconGrid does not register a navigation icon.

Files and downloads

[Download the brand guide (PDF)](/downloads/brand-guide.pdf)

<Downloads />

Review your media

Check informative images have useful alternatives, captions work in each locale, and each file URL opens in the built site. Test images in both themes and remove unwanted placeholders. Config checks warn about registered missing files; they do not validate every page-level link or remote URL. Read Validation before publishing.