Skip to main content

Pagesmith

Filesystem-first content for docs, static sites, and framework apps

Typed content collections, convention-based docs, and configurable assistant artifacts for Vite builds or framework-hosted markdown.

Start with AIManual SetupFramework GuidesAPI Reference
Terminal
npm install @pagesmith/docsnpx pagesmith-docs init --yes --ai

Features

Filesystem-First CMS

Model markdown, JSON, JSONC, JSON5, YAML, TOML, and custom loaders with Zod-backed schemas and collection APIs.

Docs With Batteries

Build a docs site from `pagesmith.config.json5` with default layouts, sidebar generation, and bundled Pagefind search.

Any Framework

Use `@pagesmith/site` as the app-facing package for collections, JSX, CSS/runtime, and Vite SSG across React, Solid, Svelte, Next.js, EJS, Handlebars, or the built-in JSX runtime. Drop to `@pagesmith/core` only when you want the headless content layer by itself.

Schema Validation

Validate frontmatter with Zod schemas and run AST-level content checks for links, headings, and code blocks at build time.

Built-in Code Renderer

Syntax highlighting with dual themes, line numbers, file titles, diff markers, collapsible sections, and copy buttons — zero config.

AI Assistant Artifacts

Generate memory files, skills, and llms.txt for Claude, Codex, and Gemini from your content collections automatically.

Packages

@pagesmith/core

Headless content layer with collections, loaders, schemas, markdown, and the content Vite plugin.

npm package @pagesmith/core version 0.10.0npmnpm0.10.00.10.0Core
@pagesmith/site

Site-building toolkit with the Pagesmith CLI, JSX runtime, CSS/runtime bundles, and Vite SSG helpers.

npm package @pagesmith/site version 0.10.0npmnpm0.10.00.10.0Site
@pagesmith/docs

Convention-based docs preset built on core and site, with default theme, Pagefind search, sidebar generation, listing pages, and layout overrides.

npm package @pagesmith/docs version 0.10.0npmnpm0.10.00.10.0Docs

Quick Start

pagesmith.config.json5
{
  $schema: "./node_modules/@pagesmith/docs/schemas/pagesmith-config.schema.json",
  contentDir: "docs",
}

Philosophy

Pagesmith is built on a few core principles:

Filesystem first. Your content directory is the source of truth. Folders define structure, markdown files define pages, and companion assets live next to the content that references them. No database, no CMS admin panel — just files.

Schema validation at the boundary. Every piece of content is validated against a Zod schema before it enters your application. Frontmatter, structured data, and even AST-level content checks (links, headings, code blocks) are enforced at build time, not at render time.

Lazy rendering. Content entries load their data eagerly but render their markdown lazily. Call entry.render() only when you need the HTML. The result is cached — subsequent calls return instantly.

Framework agnostic. The content layer does not care about your rendering stack. Define collections once, consume them in React, Solid, Svelte, Next.js, EJS, Handlebars, or the built-in JSX runtime. The Vite plugin provides virtual module imports, and the programmatic API works without Vite.

Vite native where Pagesmith owns the site build. The docs preset, CLI, development server, and SSG helpers run through Vite. The headless @pagesmith/core content layer can also run inside apps that keep their own router and build tooling.

Zero client-side runtime by default. The default output is static HTML with inline styles for code blocks. Progressive enhancements (TOC highlighting, search, sidebar toggle) are opt-in and tiny.

Three Packages

Package Purpose Install
@pagesmith/core Headless content layer, markdown pipeline, validation, loaders, schemas npm add @pagesmith/core
@pagesmith/site Re-exported content APIs, JSX runtime, CSS/runtime bundles, Vite SSG helpers, Pagesmith CLI npm add @pagesmith/site
@pagesmith/docs Convention-based docs site with theme, search, navigation npm add @pagesmith/docs

Use @pagesmith/docs when you want a complete docs site from configuration alone. Use @pagesmith/site when you want app-facing content APIs plus the shared CSS/runtime bundles, the JSX runtime, or Vite SSG helpers from one package. Use @pagesmith/core only when you want the headless content layer by itself.

Quick Start

Docs Site

Shell
npm add @pagesmith/docsnpx pagesmith-docs init --yes --ai

That is the fastest AI-first setup. It creates or backfills pagesmith.config.json5, adds starter content when needed, installs assistant artifacts, and uses GitHub Pages-friendly defaults detected from your git remote and package.json.

If you want the interactive flow instead:

Shell
npx pagesmith-docs init

Then start the dev server:

Shell
npx pagesmith-docs dev

Custom Site (content layer first)

Shell
npm add @pagesmith/core

Use createContentLayer() and entry.render() when your app already owns routing and build tooling (Next.js, template engines, custom SSR, or another framework host). If you also want the shipped markdown CSS/runtime or Vite SSG helpers, use @pagesmith/site as the app-facing package instead of layering both packages into the same integration.

For Vite-based static sites, configure pagesmithContent and pagesmithSsg and write your own layouts. See the Framework Guides for complete setup instructions for React, Solid, Svelte, Next.js, EJS, and Handlebars.

Next Steps