Styling

Mage Pages supports plain CSS and has built-in UnoCSS integration.

Static CSS

Place CSS files in your public/ directory and reference them in _html.tsx:

import type { HtmlTemplateProps } from "@mage/app/pages";

export default function Html(props: HtmlTemplateProps) {
  return (
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>{props.title}</title>
        <link rel="stylesheet" href="/__public/styles-2755b33d.css" />
      </head>
      <body>{props.children}</body>
    </html>
  );
}

During build, assets in public/ are copied to the output with content hashing for cache busting.

UnoCSS Integration

Mage Pages automatically detects UnoCSS when a uno.config.ts file exists in your project root.

Setup

Add UnoCSS to your imports in deno.json:

{
  "imports": {
    "unocss": "npm:unocss@^66"
  }
}

Create uno.config.ts:

import { defineConfig, presetTypography, presetUno } from "unocss";

export default defineConfig({
  presets: [
    presetUno(),
    presetTypography(),
  ],
});

That's it. Mage Pages will:

  1. Scan all pages, layouts, and components for class usage
  2. Generate only the CSS you use
  3. Inject the CSS into your pages automatically

See the UnoCSS documentation for configuration options, presets, and utility class reference.

Markdown Typography

Use presetTypography with the wrapperClassName option to style markdown content:

const { registerDevServer } = pages({
  markdownOptions: {
    wrapperClassName: "prose dark:prose-invert",
  },
});

Or apply prose classes in your layout:

import type { LayoutProps } from "@mage/app/pages";

export default function DocsLayout(props: LayoutProps) {
  return (
    <article className="prose dark:prose-invert max-w-none">
      {props.children}
    </article>
  );
}

Asset Hashing

During production builds, all assets including CSS files are content-hashed:

/public/styles.css → /__public/styles-a1b2c3d4.css

This enables aggressive caching while ensuring updates are always served.

Next Steps