Files & paths

Where documents live in your repo, and how a path becomes a URL.

A document is a file in your repository. The model's path says where that file is. The model's route says which URL your site serves it on.

Your repo

The folders are the registry. Adding a file is enough. Nothing else has to be imported by hand.

content/blog/hello.mdx
models/blog.ts
blocks/Hero.tsx
backmatter.config.ts
app/[[...backmatter]]/page.tsx
.backmatter/

Path	What you put there
`models/{type}.ts`	`export default defineModel(...)`. The file name is the type.
`content/…`	One document per file. The model's `path` is the exact place.
`blocks/{Name}.tsx`	A React component. The file name is the MDX tag.
`layouts/{type}.tsx`	Optional wrapper for every document of that type.
`sources/{type}.ts`	`export default defineSource(...)` for an `external: true` model. Resolves the outside record for a route; the model's `_template` document renders every record that has no file of its own. See External sources.
`backmatter.config.ts`	Workspace settings. Models are not listed here.
`app/[[...backmatter]]/page.tsx`	The route that mounts every model.
`.backmatter/`	Generated client. Gitignored. Import it as `backmatter`.

models/blog.ts

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

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

content/blog/hello.mdx is then served at /blog/hello.

Path and route

path is where the file lives. The model above uses content/blog/{slug}.mdx. A singleton omits {slug} and is one file.

route is the public URL. Set route: "/blog/{slug}" to choose it. Set route: false when the file is data for other pages and should not be a page itself.

Type is the model file name. models/blog.ts defines type: "blog".
Slug is the file name. hello.mdx is the slug hello.

withBackmatter writes .backmatter/ when you add or rename a model or a block. Adding models/faq.ts makes cms.query.faq exist. You do not register it anywhere else. Querying is how a page loads that file.

Publish writes the editor's changes back into these files. Your site reads the published files.