Core modules

@backmatter/core is the package you use to define a model, check a file, and find its path. The CLI ships from here.

Model

A model file is the content type. The file name is the type.

import { defineModel, field } from "@backmatter/core";

export default defineModel({
  type: "blog",
  path: "content/blog/{slug}.mdx",
  route: "/blog/{slug}",
  fields: {
    title: field.text({ required: true }),
    authors: field.relation("people"),
  },
});

path is where the file lives, for example content/blog/{slug}.mdx. route is the public URL. Set route: false when the file is data and should not be a page.

Every field.* call, and what it stores, is Fields. A reusable group of fields is defineObject in objects/.

Check a file

validateFrontmatter uses the same fields as publish and backmatter validate. Unknown keys are left as they are. A required field that is missing fails the check.

import { validateFrontmatter } from "@backmatter/core";

const check = validateFrontmatter(blogModel, frontmatter);

Path

repoPathFromModel turns a model and a slug into the file in the repo.

import { repoPathFromModel } from "@backmatter/core";

// blogModel.path === "content/blog/{slug}.mdx"
repoPathFromModel(blogModel, undefined, "hello");
// content/blog/hello.mdx

Config

defineConfig is backmatter.config.ts: where the folders live. Tokens stay in the environment.

import { defineConfig } from "@backmatter/core";

export default defineConfig({
  // workspaceId: "ws_…",
});