Configuration

Complete reference for Mage Pages configuration options.

pages()

The main factory function that returns dev server, build, and static server functions:

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

const { registerDevServer, build, registerStaticServer } = pages({
  siteMetadata: {
    baseUrl: "https://example.com",
    title: "My Site",
    description: "Site description",
  },
  markdownOptions: {
    shikiTheme: "github-dark",
    wrapperClassName: "prose dark:prose-invert",
  },
});

PagesOptions

Option	Type	Description
`siteMetadata`	`SiteMetadata`	Site-level metadata for sitemap/SEO
`markdownOptions`	`MarkdownOptions`	Markdown processing options

SiteMetadata

Option	Type	Description
`baseUrl`	`string`	Base URL for sitemap (e.g., `https://example.com`)
`title`	`string`	Site title (optional)
`description`	`string`	Site description (optional)

MarkdownOptions

Option	Type	Default	Description
`shikiTheme`	`string`	`"github-dark"`	Shiki theme for code blocks
`wrapperClassName`	`string`	`undefined`	CSS class for markdown wrapper

registerDevServer()

Registers the development server with hot reload:

registerDevServer(app, {
  rootDir: "./",
  basePath: "/",
  markdownOptions: {
    shikiTheme: "github-dark",
  },
});

DevServerOptions

Option	Type	Default	Description
`rootDir`	`string`	`"./"`	Project root directory
`basePath`	`string`	`"/"`	URL base path
`markdownOptions`	`MarkdownOptions`	`{}`	Markdown processing options

Features

On-demand rendering - Pages rendered when requested
Hot reload - WebSocket-based live reload on file changes
Error overlay - Visual error display in browser
Bundle caching - LRU cache for built bundles (max 50)
UnoCSS - Automatic CSS regeneration on changes

build()

Builds the site for production:

await build({
  rootDir: "./",
  outDir: "./dist",
  basePath: "/",
  markdownOptions: {
    shikiTheme: "github-dark",
    wrapperClassName: "prose",
  },
});

BuildOptions

Option	Type	Default	Description
`rootDir`	`string`	`"./"`	Project root directory
`outDir`	`string`	`"{rootDir}/dist"`	Build output directory
`basePath`	`string`	`"/"`	URL base path
`markdownOptions`	`MarkdownOptions`	`{}`	Markdown processing options

Build Process

Clean output directory
Scan for pages and system files
Build asset map with content hashes
Generate UnoCSS (if configured)
Build client bundles (parallel)
Render pages to HTML (parallel)
Render 404 and error pages
Copy hashed assets
Generate sitemap.xml and robots.txt

registerStaticServer()

Serves pre-built static files:

registerStaticServer(app, {
  rootDir: "./dist",
  basePath: "/",
});

StaticServerOptions

Option	Type	Default	Description
`rootDir`	`string`	`"./"`	Directory with built files
`basePath`	`string`	`"/"`	URL base path

Features

Serves static HTML files
Cache headers for hashed assets
404 fallback to _not-found.html

File Conventions

System Files

File	Required	Location	Purpose
`_html.tsx`	No	Root only	HTML document template
`_layout.tsx`	No	Any level	Page wrapper/layout
`_not-found.tsx`	No	Root only	Custom 404 page
`_error.tsx`	No	Root only	Custom error page

Page Files

Extension	Frontmatter	Description
`.md`	YAML block	Markdown content
`.tsx`	`frontmatter` export	Interactive Preact

Frontmatter Schema

interface Frontmatter {
  title: string; // Required
  description?: string; // Optional
  [key: string]: unknown; // Custom fields allowed
}

TypeScript Types

LayoutProps

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

export default function Layout(props: LayoutProps) {
  return <div>{props.children}</div>;
}

HtmlTemplateProps

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

export default function Html(props: HtmlTemplateProps) {
  return (
    <html>
      <head>
        <title>{props.title}</title>
      </head>
      <body>{props.children}</body>
    </html>
  );
}

Frontmatter Access

import { useFrontmatter } from "@mage/app/pages/hooks";

function Component() {
  const { title, description, customField } = useFrontmatter();
}

Head Component

import { Head } from "@mage/app/pages/head";

function Component() {
  return (
    <Head>
      <meta name="robots" content="noindex" />
    </Head>
  );
}

Environment Detection

Detect development vs production:

const isDev = Deno.env.get("DENO_ENV") !== "production";

if (isDev) {
  registerDevServer(app);
} else {
  registerStaticServer(app, { rootDir: "./dist" });
}

Shiki Themes

Available themes for code highlighting:

Theme	Description
`github-dark`	GitHub's dark theme (default)
`github-light`	GitHub's light theme
`one-dark-pro`	Atom One Dark
`dracula`	Dracula theme
`nord`	Nord theme
`vitesse-dark`	Vitesse dark
`vitesse-light`	Vitesse light
`min-dark`	Minimal dark
`min-light`	Minimal light

See Shiki themes for the complete list.

Base Path

For sites not hosted at the root domain:

// Site at https://example.com/docs/
const { build } = pages({
  siteMetadata: { baseUrl: "https://example.com" },
});

await build({ basePath: "/docs" });

All internal links and assets will be prefixed with /docs.