content.config.ts

content.config.ts is the source of truth for the content model. Import its runtime helpers from @lupinum/ginko-content/config; put parsing and runtime behavior in the content module options.

import {
  defineCollection,
  defineContentConfig,
  fields
} from '@lupinum/ginko-content/config'

export const articles = defineCollection({
  type: 'page',
  source: 'articles/**/*.md',
  schema: fields.object({
    title: fields.text().required(),
    publishedAt: fields.datetime()
  })
})

export default defineContentConfig({
  collections: { articles }
})

Root config

defineContentConfig(config: ContentConfig): ContentConfig

defineContentConfig() preserves type inference and assigns each collection map key as the collection handle's name.

Register a custom provider by name:

export default defineContentConfig({
  provider: 'custom',
  providers: {
    custom: '@acme/content-provider'
  },
  collections: { articles }
})

The provider module must implement the provider contract.

Collections

defineCollection(config: DefineCollectionObject): ContentCollectionHandle

The object form of source moves exclude onto the normalized collection:

const docs = defineCollection({
  type: 'page',
  source: {
    include: ['docs/**/*.md', 'shared/**/*.md'],
    exclude: 'docs/private/**'
  }
})

Use locale-specific route mounts when translated URLs differ:

const docs = defineCollection({
  type: 'page',
  source: 'docs/**/*.md',
  i18n: true,
  route: { en: '/docs', de: '/dokumentation' }
})

i18n: true inherits the module locale policy. i18n: false opts a collection out. The object form owns defaultLocale and locales for that collection.

With the default strict: true, a document that fails the collection schema is rejected. Set strict: false only when schema failures should warn and pass through the original document; it does not change the Zod schema's own unknown-key policy.

CMS options

cms supplements the schema with editor-specific information. It does not replace the collection or schema as the content contract.

cms.route accepts mode, pathPrefix, slugMode, rootSlug, singleton, and allowMultipleRoots. slugMode is one of 'shared', 'localized', 'stable', or 'localizedStable'.

A cms.fields entry may set type, label, description, required, localized, searchable, sortable, defaultValue, validation, options, relation, nested fields, min, max, step, slugFrom, language, and an opaque editor object. Prefer fields.* metadata when it can express the same rule once in the schema.

Collection agent options

const docs = defineCollection({
  type: 'page',
  agent: {
    section: 'documentation',
    markdown: {
      includeInIndex: true,
      includeInFull: true,
      metadata: ['title', 'description', 'url']
    }
  }
})

agent.section assigns pages to a root agent section. agent.markdown is a boolean or an object with includeInIndex, includeInFull, and metadata.

Schema fields

fields produces Zod schemas with CMS metadata. Fields are optional unless .required() is applied; fields.object() itself is required.

Every field schema supports these metadata modifiers:

fields.text()
  .label('Title')
  .help('Shown in cards and SEO metadata')
  .localized()
  .required()

fields.number().shared()

Plain Zod schemas remain supported. A schema that outputs a JavaScript Date is rejected at ingest; use fields.date() or fields.datetime() so stored values remain portable strings.

References

reference(collection?: string): ContentReferenceSchema

reference() marks an authored reference without CMS field metadata. Pass a collection name to constrain the target, or omit it for a cross-collection reference.

import { reference } from '@lupinum/ginko-content/config'
import { z } from 'zod'

schema: z.object({
  author: reference('authors'),
  related: z.array(reference('articles')).default([])
})

Use fields.relation() and fields.relations() when the same schema should also describe the CMS editor.

Root agent config

The root agent object owns site-wide output policy. The collection-level agent object only chooses exposure and section membership.

Localized site values and page routes accept either a string or a locale map. An app page requires id, route, section, title, description, and render(ctx); its title and description may also be sync or async functions of ctx. It may set updated, includeInIndex, includeInFull, and metadata.

Use the identity helpers to preserve literal inference:

import {
  defineAgentAppPage,
  defineAgentMarkdownPolicy,
  defineAgentMetadataFields,
  defineAgentSection
} from '@lupinum/ginko-content/config'

const metadata = defineAgentMetadataFields(['title', 'description', 'url'])

export default defineContentConfig({
  agent: {
    markdown: defineAgentMarkdownPolicy({
      metadata: { enabled: true, defaultFields: metadata }
    }),
    sections: [
      defineAgentSection({ id: 'documentation', title: 'Documentation', order: 10 })
    ],
    pages: [
      defineAgentAppPage({
        id: 'support',
        route: '/support',
        section: 'documentation',
        title: 'Support',
        description: 'How to get help.',
        render: () => '# Support\n\nContact the maintainers.'
      })
    ]
  },
  collections: { articles }
})

agentMetadataFields contains the allowed built-ins: title, description, url, route, locale, section, collection, source, and updated.

Metadata and slug utilities

getContentFieldMetadata(schema): ContentFieldMetadata | null
isContentFieldSchema(schema): boolean
slugifyUrlSegment(value, options?: { lower?: boolean }): string

getContentFieldMetadata() reads the metadata attached by fields.*; isContentFieldSchema() is its type guard. slugifyUrlSegment() transliterates and normalizes one URL segment, lowercasing by default. Pass { lower: false } to preserve ASCII letter case.

defineContentConfig() throws when an authored collection name disagrees with its map key. defineCollection() rejects the removed (name, config) signature; put the desired name in the collections map instead.