Special-Purpose Pages

Themes can include pre-defined pages via theme.pagesDir. These pages follow standard routing rules, but user-provided pages always take precedence in the event of a route conflict.

This feature is ideal for providing:

Theme-Provided Pages

Define your pages directory in the theme entry point:

export default () => ({
	theme: {
		root: '.',
		pagesDir: './pages'
	}
})

Differentiated Layouts

The most effective way to implement specialized layouts is by defining a layout property in the page frontmatter.

Example menu.mdx:

---
title: Menu
layout: menu
hidden: true
---

# Menu content

Template implementation:

const MenuLayout = ({ ctx, PageContent }) => (
	<div class="menu-layout">
		<h1>{ctx.page.title}</h1>
		<PageContent />
	</div>
)

const DocLayout = ({ ctx, PageContent }) => (
	<div class="doc-layout">
		<aside>{/* Sidebar */}</aside>
		<main>
			<PageContent />
		</main>
	</div>
)

export default function PageTemplate({ PageContent, ExtraHead, ctx }) {
	const layout = ctx.page.frontmatter?.layout
	return (
		<>
			<html>
				<head>
					<ExtraHead />
					<title>{ctx.page.title || ctx.site.name}</title>
				</head>
				<body>
					{layout === 'menu' ? (
						<MenuLayout ctx={ctx} PageContent={PageContent} />
					) : (
						<DocLayout ctx={ctx} PageContent={PageContent} />
					)}
				</body>
			</html>
		</>
	)
}

Interactive Components

For pages requiring complex interactivity (e.g., contact forms), we recommend using client-only components. Your theme can provide these in its components/ directory (e.g., ContactForm.client.jsx), which users can then drop into their MDX pages.

Standalone HTML Pages

Special-purpose pages are not limited to MDX. You can include pure .html files in your theme's pagesDir. These are processed by Vite and passed through your theme's template.

This approach is excellent for standalone landing pages or embedded tools that should omit standard documentation elements like sidebars or ToCs. You can use ctx.page.path.endsWith('.html') within your template to apply a "standalone" layout.

Path and Asset Resolution

Methanol automatically resolves asset paths during the build process. While withBase() is generally not required for theme-provided static assets in public/, it remains a reliable tool for generating dynamic URLs that must remain base-path aware across different environments.