Serve images, fonts, and other static files alongside your Zorto site.

Zorto provides two mechanisms for assets: the static/ directory for site-wide files, and co-located assets for page-specific files.

Static files #

Place site-wide assets in the static/ directory at your project root. Everything inside is copied verbatim to the output directory during build:

📂my-site/
├── 📂static/
    ├── 📝favicon.ico→ /favicon.ico
    ├── 📂images/
        ├── 📝logo.png→ /images/logo.png
    ├── 📂fonts/
        ├── 📝custom.woff2→ /fonts/custom.woff2
    ├── 📝robots.txt→ /robots.txt

Files in static/ are copied to the root of your output directory.

Reference them with absolute paths in templates or markdown:

<link rel="icon" href="/favicon.ico">
<img src="/images/logo.png" alt="Logo">

![Logo](/images/logo.png)

The directory structure is preserved. Nested directories work as expected.

Co-located assets #

Place images and files next to a page’s markdown by using a directory with an index.md file:

📂content/posts/my-post/
├── 📝index.mdpage → /posts/my-post/
├── 📝photo.jpg→ /posts/my-post/photo.jpg
├── 📝diagram.svg→ /posts/my-post/diagram.svg
├── 📝data.json→ /posts/my-post/data.json

Assets live alongside the page that uses them.

Reference co-located assets with relative paths in your markdown:

![A photo](photo.jpg)
![A diagram](diagram.svg)

Any non-markdown file inside a content directory is treated as a co-located asset. During the build, Zorto copies these files to the page’s output directory, preserving the relative path relationship.

When to use each approach #

ApproachUse forReference with
static/Favicons, global images, fonts, robots.txt, _headersAbsolute paths (/images/logo.png)
Co-locatedPage-specific images, diagrams, downloadsRelative paths (photo.jpg)

Images #

For images in markdown, use standard markdown syntax:

![Alt text](photo.jpg)
![Alt text](/images/hero.png)

Tip

Always include alt text for accessibility. Keep image file sizes small — Zorto does not optimize images at build time. Use tools like imagemagick, sharp, or squoosh before adding images to your project.

Supported formats include .jpg, .png, .svg, .gif, .webp, and any other format browsers can display.

Fonts #

Host fonts locally by placing them in static/fonts/:

📂static/fonts/
├── 📝inter-regular.woff2
├── 📝inter-bold.woff2

Load them in your stylesheet:

// sass/custom.scss
@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-regular.woff2") format("woff2");
  font-weight: 400;
  font-display: swap;
}

@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-bold.woff2") format("woff2");
  font-weight: 700;
  font-display: swap;
}

body {
  font-family: "Inter", sans-serif;
}

Use font-display: swap to prevent invisible text while fonts load.

Caching and cache busting #

Static files are served with whatever caching policy your hosting provider applies. Zorto does not add cache-busting hashes to filenames.

For aggressive caching strategies, use your hosting provider’s headers configuration. For example, with Netlify:

# static/_headers
/fonts/*
  Cache-Control: public, max-age=31536000, immutable
/images/*
  Cache-Control: public, max-age=86400

SCSS-compiled CSS files are regenerated on every build, so browsers fetch the latest version when the content changes and the hosting provider’s cache expires.