Configure a Contentbit project

Use contentbit.config.ts to stop repeating project flags across package scripts, local commands, Studio, and agent workflows. contentbit init creates this file for new projects. For an existing setup, add it at the project root:

import { defineContentConfig } from '@contentbit/core'

export default defineContentConfig({
  content: 'content/**/*.{md,mdx}',
  registry: './blocks/registry.ts',
  genericBlocks: true,
  links: {
    resolve: 'same-locale-key',
    localeField: 'locale',
    keyField: 'key',
    slugField: 'slug',
  },
  seo: './contentbit.seo.config.ts',
})

Paths and globs are relative to the config file. Contentbit searches upward from the current directory for contentbit.config.ts, .mts, .mjs, or .js, which makes the nearest config win in a monorepo.

With a config present, daily commands need no repeated project flags:

contentbit validate
contentbit doctor
contentbit studio
contentbit stats
contentbit links
contentbit instructions --audience llm
contentbit brief <key-or-slug>

Explicit files, globs, --registry, --seo-config, link fields, and --no-generic-blocks override the config for one invocation. Existing projects that keep the full invocation in package scripts continue to work; config discovery takes precedence when both are present.

Check the discovered project

Run a command from the project root without a glob or registry flag:

contentbit validate --strict-warnings

If the command scans the expected files, the other project-aware commands will use the same configuration. In a monorepo, run from the package that owns the nearest config.

Use an explicit option only for a one-off override. For example:

contentbit doctor "drafts/**/*.md" --no-seo

@contentbit/studio is installed separately from the base CLI so validation and one-shot init installs stay lightweight. contentbit init installs both development packages for you. When adding Studio manually:

pnpm add -D @contentbit/studio

See the configuration reference for every field, default, discovery rule, and override.