Nextra Migration route for SVGs

[cefn]

We are trying to upgrade our Nextra 2 docs to a newer version but we are facing a regression. Can anyone tell us how to align with the previously working behaviour for SVG images.

Previously an SVG was aliased as a static file simply by...

![Merge Request Pipeline](../../flowcharts/mr_pipeline.drawio.svg)

...becoming aliased to https://hostname.com/site-path/_next/static/media/mr_pipeline.drawio.fa66b4e1.svg as expected.

Since upgrading to Nextra 3 all builds fail with the following...

./pages/ci/release_and_deploy.md:4
Error: Image import "/Users/username/workspace/site-path/docs/public/flowcharts/mr_pipeline.drawio.svg" is not a valid image file. The image may be corrupted or an unsupported format.

The image file has not changed and it IS a valid image file.

[manimovassagh]

This is a known breaking change in Nextra 3+. The new version uses Next.js image optimization by default, which doesn't handle SVGs the same way.

The fix is to treat SVGs as static assets instead of letting the bundler process them as images. You have a couple of options:

Option 1: Move SVGs to public/ and reference them with absolute paths

![Merge Request Pipeline](/flowcharts/mr_pipeline.drawio.svg)

Put the file at public/flowcharts/mr_pipeline.drawio.svg. This bypasses the image import pipeline entirely.

Option 2: Configure Next.js to not optimize SVGs

In your next.config.mjs:

import nextra from "nextra";

const withNextra = nextra({ /* your nextra config */ });

export default withNextra({
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: "attachment",
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
});

Option 3: Use an <img> tag directly in MDX

<img src="/flowcharts/mr_pipeline.drawio.svg" alt="Merge Request Pipeline" />

Option 1 is the cleanest migration path for a large number of SVGs -- just move them all into public/ and update the paths to be absolute (drop the relative ../../ prefixes). It's also the most future-proof since it doesn't depend on bundler behavior at all.