Images and Assets

Methanol provides two primary methods for managing static assets: global storage in the public/ directory and local referencing for page-specific files.

The public/ Directory

Files placed within the public/ directory are served directly from the site root.

Even when deploying to a subpath (site.base !== '/'), you typically do not need to wrap public asset paths with ctx.withBase(). Methanol automatically resolves these paths at build time.

However, if you are generating URLs dynamically within JavaScript (e.g., in client-only components) and encounter resolution issues in the development environment, ctx.withBase('/...') serves as a reliable workaround.

public/
  logo.png
  downloads/
    brochure.pdf

Referencing assets in MDX:

![Logo](/logo.png)
[Download Brochure](/downloads/brochure.pdf)

Local Asset Referencing

You may also store images alongside your page files and reference them using relative paths:

pages/
  guide/
    writing.mdx
    writing-diagram.png

![Diagram](./writing-diagram.png)

Global Styles and Scripts

If a pages/style.css file exists, Methanol automatically injects it into every page. Similarly, pages/index.js or pages/index.ts will be injected as a module script globally.

These URLs are automatically adjusted for Base Path during production builds (equivalent to utilizing ctx.withBase('/style.css') or ctx.withBase('/index.js')).

<link rel="stylesheet" href="/style.css" />
<script type="module" src="/index.js"></script>