Media

Use public/media for static files that should be served as-is. MDX pages can reference those files with root-relative /media/... URLs, so authors do not need imports for common images or PDFs. Always use that source form: do not include Astro’s configured base, because Oxiquill adds it during the Markdown transform.

Image Files

Markdown image syntax is the shortest option. Use specific alt text that describes the image content.

![PNG sample with color bands](/media/examples/sample.png)

JPEG files use the same URL pattern.

![JPEG sample with a grid and gradient](/media/examples/sample.jpg)

PDFs

For PDFs, include both an embedded frame and a normal link. The frame lets readers preview the document in place, and the link gives them a direct way to open or download it.

<iframe class="media-frame" src="/media/examples/sample.pdf" title="Sample PDF"></iframe>

[Open the PDF in a new tab](/media/examples/sample.pdf)

Open the PDF in a new tab

Placement Rules

• Put public files under public/media.
• Reference them with root-relative /media/... URLs; never add Astro’s configured base manually.
• Keep generated media out of the docs tree unless the file itself is the intended source asset.
• Use stable sample files so tests and screenshots remain deterministic.