Framework Integrations

Pagesmith’s content layer is framework-agnostic. Define collections once in content.config.ts, then consume entries through virtual imports or the programmatic content-layer API in any rendering stack.

Read this diagram left to right: headless integrations can stay on @pagesmith/core, Vite and custom-site paths usually live on @pagesmith/site, and @pagesmith/docs is the convention-based path when you want a docs site with built-in navigation, search, and theme.

Three Approaches

Virtual Content Modules (pagesmithContent)

Used by the React, Solid, and Svelte integrations. You define collections in content.config.ts and the pagesmithContent Vite plugin exposes them as virtual:content/* modules with pre-rendered HTML:

1import guideCollection from "virtual:content/guide";

Programmatic Content Layer (createContentLayer)

Used by the EJS, Handlebars, and Blog Site integrations. You create a content layer directly and call getCollection() / entry.render() at render time:

1const layer = createContentLayer({ collections: { guide, blog, pages }, root });2const entries = await layer.getCollection("guide");3const rendered = await entries[0].render();

Framework-Hosted Rendering (createContentLayer + app-owned routing)

Used by the Next.js integration. The host app keeps routing, layout, metadata, and build tooling, while Pagesmith provides the content layer and markdown pipeline:

1const layer = createContentLayer(defineConfig({ collections }));2const entry = await layer.getEntry("posts", "hello-world");3const rendered = await entry?.render();

Import @pagesmith/site/css/content and @pagesmith/site/runtime/content only when you want the shared markdown prose, code-block chrome, tabs, copy buttons, and collapse behavior.

Convention-Based (@pagesmith/docs)

Used by the Doc Site integration. You write markdown in a content/ tree and configure the site in pagesmith.config.json5. No Vite config or entry server needed.

Example Matrix

The repo includes a full example matrix. Each example is self-contained with its own package.json, content, styles, and build configuration.

Vite Plugins and Shared Presentation Layer

The Vite-based examples wire Pagesmith through plugins. Framework-hosted examples such as Next.js use the content layer directly and opt into the shared presentation layer only when they want shipped markdown styling and code-block behavior.

Shared Behavior

Across the examples, Pagesmith is responsible for the same core content jobs:

• Loading content from markdown files
• Validating frontmatter against Zod schemas
• Processing markdown through the unified pipeline (GFM, math, syntax highlighting, heading slugs)
• Extracting headings and read time from rendered markdown

Depending on the integration shape, @pagesmith/site may also handle:

• Copying companion assets into the final build
• Pre-rendering and preview server behavior
• Pagefind indexing for full-text search

Theme and Shell Choices

The examples do not all share the same page chrome:

• Docs-like and standalone site examples can implement the full Pagesmith theme system, including appearance/theme/text-size controls and persisted preferences.
• Framework-hosted examples such as Next.js can keep the outer shell fully native to the host app and reuse only the shared content CSS/runtime.
• Template and custom-site examples can pick either approach depending on how much of the site shell they want Pagesmith to own.

For full details, see the Theming reference.

CSS Imports

All examples can use pre-built CSS from @pagesmith/site:

JSX Runtime

Two JSX runtimes are used across the examples:

• Framework JSX (React, Solid, Svelte) — each framework’s own JSX transform via their Vite plugin
• Pagesmith server-side JSX — @pagesmith/site/jsx-runtime powers custom site layouts such as the Blog Site, while @pagesmith/docs/jsx-runtime powers docs layout overrides. Both produce HTML strings with h() and Fragment(), use class (not className), and use innerHTML for raw HTML.

Choosing a Pattern

Read Next

• Vite Framework Apps — React, SolidJS, Svelte
• Next.js (App Router) — createContentLayer() inside a Next.js app
• Template Engines — EJS, Handlebars
• Doc Site
• Blog Site