Skip to content
NaturaLife Astro Theme

Images and Fonts

Learn how to add images to MDX content, replace registered page images, manage responsive crops, and customize the locally served fonts.

Put a source image anywhere suitable under src/assets/, for example src/assets/garden.jpg. In src/content/blog/posts/garden-notes.mdx, a cover and imported body image use paths relative to that record:

---
id: garden-notes
slug: garden-notes
title: Garden notes
description: Notes from our garden.
publishDate: "2026-10-29"
author: editor
categories: [garden]
coverImage: ../../../assets/garden.jpg
coverImageAlt: Our garden in autumn
---
import ContentImage from '@rtthemes/naturalife/components/ContentImage.astro';
import photo from '../../../assets/garden.jpg';
<ContentImage src={photo} alt="Our garden in autumn" />

Create the referenced author/category as shown in Content and Collections. Imported images need no registry entry. Author photo and gallery images[].image paths are also relative to their content record.

ContentImage and ContentGallery use the imported-image pipeline. When passing imported Astro image metadata to other theme components, use the public contentImage() helper from @rtthemes/naturalife/content-images to produce the expected props and viewer URLs. Do not treat a remote URL as imported image metadata.

Designed JSON refers to logical assets/... output URLs. Its source images and crops are registered in src/content/media/images.json.

To replace Home I’s first slider image:

  1. Add src/assets/images/garden-slide.png with proportions and transparency suitable for the original design.
  2. In images.json, change assets["slide5-2"].source to assets/images/garden-slide.png.
  3. Keep the existing output paths, dimensions and transparent profile, then preview the slider.

This changes one image file and one registry file. The page JSON already refers to the generated output, so it needs no edit. Registry source is relative to src/; output path is a logical public URL.

For a new designed-section image, add the master, a registry record with a unique ID/output path, and the page JSON reference. Copy a suitable record and choose intentional dimensions/profile. Use per-output source for a prepared crop, or focalPoint: [0.5, 0.3] for a crop focus when needed. You can instead use imported images in a local Astro section.

Demo photographs, brand artwork and product images live under src/assets/images/demo/. Functional UI files such as flags, arrows and cursors are separate. Do not remove functional assets merely because you are replacing demo photography.

Changing an MDX cover does not change separately authored presentation galleries or backgrounds. Keep original masters and applicable asset notices. public/assets/, .cache/images/ and dist/ are generated output; rebuild them rather than editing their thumbnails.

The theme serves bundled Roboto, Roboto Slab and Caveat WOFF2 fonts locally through Astro’s Fonts API. Default font builds do not need a font-service download. Your project’s existing astro.config.mjs can replace a family by defining the same CSS variable:

import { defineConfig, fontProviders } from 'astro/config';
// Keep your existing mdx and naturalife imports and integration options.
// Add this fonts option to your existing defineConfig object:
const fonts = [{
name: 'Customer Font',
cssVariable: '--nf-font-body',
provider: fontProviders.local(),
options: {
variants: [{
src: ['./src/assets/fonts/customer.woff2'],
weight: '100 900',
style: 'normal',
}],
},
fallbacks: ['Arial', 'sans-serif'],
}];

Set the existing config’s fonts option to that array; keep its integrations and other options. Add a properly licensed font at the specified path, with weights/styles matching the declared range. Use --nf-font-heading or --nf-font-secondary to replace those families. A replacement covers the entire default family, so include every style you need. Body and menu share the body family; customer CSS can override --font-menu separately.

The supplied layouts already include the font head. A full custom HTML layout must include FontHead, SeoHead and virtual:naturalife/styles once. Do not re-add old font CSS or duplicate font-face rules. Font preload is off by default; choose only necessary weights/styles if you customize it. See Astro’s font guide for provider configuration.