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  shiki?: {7    themes: { light: string; dark: string };8    langAlias?: Record<string, string>;9    defaultShowLineNumbers?: boolean;10  };11};

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});

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 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};

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 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() });