API Reference

1import { defineCollection, z } from "@pagesmith/core";23const posts = defineCollection({4  loader: "markdown",5  directory: "content/posts",6  schema: z.object({7    title: z.string(),8    date: z.coerce.date(),9  }),10});

1import { defineCollection, defineCollections, z } from '@pagesmith/core'23const collections = defineCollections({4  posts: defineCollection({ ... }),5  authors: defineCollection({ ... }),6})

1import { defineConfig } from "@pagesmith/core";23const config = defineConfig({4  collections: { posts, authors },5  root: process.cwd(),6  markdown: { shiki: { themes: { light: "github-light", dark: "github-dark" } } },7  plugins: [],8});

1import { createContentLayer } from "@pagesmith/core";23const layer = createContentLayer(config);

1type RenderedContent = {2  html: string; // Processed HTML3  headings: Heading[]; // Extracted headings for TOC4  readTime: number; // Estimated read time in minutes5};

1import { convert } from "@pagesmith/core";23const result = await convert("# Hello\n\nWorld", {4  markdown: { shiki: { themes: { light: "github-light", dark: "github-dark" } } },5});6// result.html, result.headings, result.toc, result.frontmatter

1type ConvertResult = {2  html: string;3  headings: Heading[];4  /** @deprecated Use `headings` instead. */5  toc: Heading[];6  frontmatter: Record<string, any>;7};

1type Heading = {2  depth: number; // 1-63  text: string; // Heading text content4  slug: string; // URL-safe id5};

1type MarkdownConfig = {2  remarkPlugins?: any[];3  rehypePlugins?: any[];4  allowDangerousHtml?: boolean;5  math?: boolean | "auto";6  images?: {7    lazyLoading?: boolean; // default true8    eagerCount?: number; // default 19  };10  shiki?: {11    themes: { light: string; dark: string };12    langAlias?: Record<string, string>;13    defaultShowLineNumbers?: boolean;14  };15};

1import { defineConfig } from "@pagesmith/core";23export default defineConfig({4  collections: {5    /* ... */6  },7  markdown: {8    images: { eagerCount: 2 }, // treat the first two images as eager9  },10});

1type ContentLayerConfig = {2  collections: CollectionMap;3  root?: string;4  markdown?: MarkdownConfig;5  assets?: { hashFilenames?: boolean; outputDir?: string };6  plugins?: ContentPlugin[];7  strict?: boolean;8};

1type CollectionDef<S> = {2  loader: LoaderType | Loader;3  directory: string;4  schema: S;5  include?: string[];6  exclude?: string[];7  computed?: Record<string, (entry: any) => any>;8  transform?: (entry: RawEntry) => RawEntry | Promise<RawEntry>;9  filter?: (entry: any) => boolean;10  slugify?: (filePath: string, directory: string) => string;11  validate?: (entry: any) => string | undefined;12  validators?: ContentValidator[];13  disableBuiltinValidators?: boolean;14};

1type ContentPlugin = {2  name: string;3  rehypePlugin?: () => (tree: any) => void;4  remarkPlugin?: () => (tree: any) => void;5  validate?: (entry: { data: Record<string, any>; content?: string }) => string[];6};

1type ValidationIssue = {2  message: string;3  severity: "error" | "warn";4  field?: string;5};

1type ValidationResult = {2  collection: string;3  entries: Array<{4    slug: string;5    filePath: string;6    issues: ValidationIssue[];7  }>;8  errors: number;9  warnings: number;10};

1type ContentValidator = {2  name: string;3  validate(ctx: ValidatorContext): ValidationIssue[] | Promise<ValidationIssue[]>;4};

1type ValidatorContext = {2  filePath: string;3  slug: string;4  collection: string;5  rawContent?: string;6  data: Record<string, any>;7  mdast?: Root;8};

1{2  "compilerOptions": {3    "jsx": "react-jsx",4    "jsxImportSource": "@pagesmith/site"5  }6}

1type MarkdownResult = {2  html: string;3  headings: Heading[];4  frontmatter: Record<string, any>;5};

1import { buildCss } from "@pagesmith/site/css";23const css = buildCss("./styles/main.css", { minify: true });

1import { z } from "@pagesmith/core";23const schema = z.object({4  title: z.string(),5  date: z.coerce.date(),6});

1function defaultConcurrency(): number; // max(1, os.availableParallelism())23function mapWithConcurrency<T, R>(4  items: readonly T[],5  mapper: (item: T, index: number) => Promise<R>,6  concurrency?: number, // defaults to defaultConcurrency(); values < 1 clamp to 17): Promise<R[]>;

1import { mapWithConcurrency } from "@pagesmith/core";23const sizes = await mapWithConcurrency(imagePaths, (path) => statImage(path), 4);4// sizes[i] corresponds to imagePaths[i], regardless of completion order

1import { pagesmithContent } from "@pagesmith/core/vite";2import collections from "./content.config";34export default defineConfig({5  plugins: [pagesmithContent(collections)],6});

1{ id: string, contentSlug: string, html: string, headings: Heading[], frontmatter: InferCollectionData<T> }

1{ id: string, contentSlug: string, data: InferCollectionData<T> }

1import { pagesmithSite } from "@pagesmith/site/vite";2import collections from "./content.config";34export default defineConfig({5  plugins: [6    pagesmithSite({7      collections,8      content: {9        /* PagesmithContentPluginOptions, minus `collections` */10      },11      ssg: { entry: "./src/entry-server.tsx" }, // pass `false` to skip SSG (e.g. Next.js)12    }),13  ],14});

1import { pagesmithContent, pagesmithSsg } from "@pagesmith/site/vite";2import collections from "./content.config";34export default defineConfig({5  plugins: [pagesmithContent(collections), pagesmithSsg({ entry: "./src/entry-server.tsx" })],6});

1import { pagesmithSsg } from "@pagesmith/site/vite";23export default defineConfig({4  plugins: [5    pagesmithSsg({6      entry: "./src/entry-server.tsx",7      pagefind: true,8      contentDirs: ["content"],9    }),10  ],11});

1type SsgBeforeBuildContext = {2  rootDir: string; // Absolute path to the project root (Vite's resolved `root`)3  outDir: string; // Absolute path to the build output directory4  config: ResolvedConfig; // Vite's fully resolved config for this build5  logger: Logger; // Prefixed `pagesmith:ssg` logger (from @pagesmith/core)6};

1import { writeFileSync } from "fs";2import { generateFeed } from "@pagesmith/site/ssg-utils";3import { pagesmithSsg } from "@pagesmith/site/vite";45pagesmithSsg({6  entry: "./src/entry-server.tsx",7  async beforeBuild({ outDir, config, logger }) {8    const posts = await loadPublishedPosts();9    const xml = generateFeed(posts, {10      origin: "https://example.com",11      basePath: config.base.replace(/\/+$/, ""),12      title: "Example Blog",13      description: "Latest posts",14      language: "en",15    });16    writeFileSync(`${outDir}/rss.xml`, xml);17    logger.info(`rss.xml written with ${posts.length} item(s)`);18  },19});

1type SsgRenderConfig = {2  base: string; // Base path (e.g., '/my-site')3  root: string; // Absolute project root4  cssPath: string; // Path to the built CSS asset5  jsPath?: string; // Path to the built JS asset6  searchEnabled: boolean;7  isDev: boolean;8};

1type PrerenderOptions = {2  /** Absolute path to the client build output directory (e.g., `dist/`) */3  outDir: string;4  /** Absolute path to the built SSR entry module (e.g., `dist/.server/entry-server.js`) */5  serverEntry: string;6  /** Routes to pre-render (e.g., `['/', '/about', '/posts/hello-world']`) */7  routes: string[];8  /** HTML placeholder to replace with rendered content (default: `'<!--ssr-outlet-->'`) */9  placeholder?: string;10  /** Remove the server build directory after pre-rendering (default: true) */11  cleanup?: boolean;12  /** Maximum routes rendered in parallel (default: host available parallelism) */13  concurrency?: number;14};

1import { build } from "vite";2import { prerenderRoutes } from "@pagesmith/site/vite";34// 1. Client build5await build({ build: { outDir: "dist" } });67// 2. SSR build8await build({ build: { ssr: "src/entry-server.tsx", outDir: "dist/.server" } });910// 3. Pre-render11await prerenderRoutes({12  outDir: resolve("dist"),13  serverEntry: resolve("dist/.server/entry-server.js"),14  routes: ["/", "/about", "/posts/hello-world"],15});

1type FeedEntry = {2  title: string;3  /** Route path; may already carry the base path (`withBasePath` is idempotent) */4  path: string;5  /** Entries without one are excluded from the feed */6  publishedDate?: string | Date;7  /** Falls back to `title` when omitted */8  description?: string;9  /** Emitted as `<category>` elements */10  tags?: string[];11};1213type FeedConfig = {14  origin: string; // e.g. 'https://example.com'15  basePath?: string; // e.g. '/blog'16  title: string; // channel <title>17  description: string; // channel <description>18  language: string; // channel <language>, e.g. 'en'19  limit?: number; // max items, default 5020  buildDate?: Date; // <lastBuildDate>; defaults to now21};2223function generateFeed(entries: FeedEntry[], config: FeedConfig): string;

1import { writeFileSync } from "fs";2import { generateFeed } from "@pagesmith/site/ssg-utils";34const xml = generateFeed(posts, {5  origin: "https://example.com",6  basePath: "/blog",7  title: "Example",8  description: "Latest posts",9  language: "en",10});11writeFileSync("dist/rss.xml", xml);

1type SitemapConfig = {2  origin: string;3  basePath?: string;4};56function generateSitemap(routes: string[], config: SitemapConfig): string;

1import { generateSitemap } from "@pagesmith/site/ssg-utils";23const xml = generateSitemap(["", "/about", "/blog/hello"], {4  origin: "https://example.com",5  basePath: "/docs",6});

1import { runBuildValidation } from "@pagesmith/site/build-validator";23const exitCode = runBuildValidation({4  outDir: resolve("dist"),5  basePath: "/my-site",6  checkSitemap: true,7  checkBundledAssets: true,8});9process.exit(exitCode);

1type SiteDocumentSeo = {2  locale?: string;3  twitterHandle?: string;4  defaultOgType?: string;5  jsonLd?: boolean; // default true6};

1import {2  buildArticleStructuredData,3  buildWebsiteStructuredData,4  serializeJsonLd,5} from "@pagesmith/site";67const data = buildArticleStructuredData({8  type: "BlogPosting",9  headline: "Hello, world",10  description: "An example post",11  datePublished: "2026-01-15",12  author: "Ada Lovelace",13  url: "https://example.com/blog/hello",14  image: "https://example.com/og/hello.png",15});1617const script = `<script type="application/ld+json">${serializeJsonLd(data)}</script>`;

1type Template = {2  name: string;3  description: string;4  source: "local" | "github";5  path: string;6  dependency: "@pagesmith/core" | "@pagesmith/site" | "@pagesmith/docs";7  scripts: Record<string, string>;8};

1import { createProject, listTemplates } from "@pagesmith/core/create";23// List available templates4console.log(listTemplates());56// Scaffold a new project7await createProject("my-docs", "docs");

1import { docsPreset } from "@pagesmith/docs/preset";23const docs = docsPreset();45// Build the docs site6await docs.build({ configPath: "./pagesmith.config.json5" });78// Start dev server9await docs.dev({ configPath: "./pagesmith.config.json5", port: 3000 });1011// Preview built output12await docs.preview({ configPath: "./pagesmith.config.json5", port: 4000 });1314// Run validate; returns the process exit code (0 = pass)15const code = await docs.validate({ configPath: "./pagesmith.config.json5" });1617// init / mcp accept argv-style strings and forward to the matching CLI command18await docs.init(["--ai", "--yes"]);19await docs.mcp(["--stdio"]);

1import collections from "../content.config.js";2import { createContentLayer, defineConfig } from "@pagesmith/core";3import { startCoreMcpServer } from "@pagesmith/core/mcp";45const layer = createContentLayer(defineConfig({ collections }));6await startCoreMcpServer({ layer, rootDir: process.cwd() });