Collections & Fields

Collections are the backbone of GitCMS. Each collection represents a type of content — blog posts, documentation pages, team members, product changelogs — with a defined set of fields that make up the frontmatter schema.

What is a collection?

A collection maps to a directory in your repository. Every Markdown or MDX file in that directory becomes an entry in the collection. The frontmatter fields in each file are defined by the collection's frontmatter schema, and GitCMS renders a structured form for editing them.

src/content/blog/          ← collection "blog"
  ├── hello-world.mdx      ← entry
  ├── second-post.mdx      ← entry
  └── draft-ideas.mdx      ← entry

Managing collections

Collections are configured through the Settings page in the GitCMS web app. You can add, edit, and remove collections and their fields entirely through the UI. The configuration is saved into your repository's .gitcms/ folder — you don't need to edit it manually.

Collection settings

Collection i18n paths

When site i18n is enabled, each collection can use locale-aware paths.

• Strategy is path-based (path).
• Default behavior uses locale folders (/blog/fr/...).
• You can set per-locale overrides when your framework uses custom folders.

Example override pattern:

i18n:
  enabled: true
  locales: [en, fr]
  default_locale: en
  prefix_default_locale: false
collections:
  - name: blog
    git_path: /content/blog/
    i18n:
      enabled: true
      strategy: path
      locale_paths:
        fr: /content/fr/blog/

Filename patterns

The filename pattern controls how new files are named when created through the CMS. You build patterns using the visual pattern builder in Settings, combining text and field references.

Examples:

• {title} — derives filename from the title field (e.g. hello-world.mdx)
• {date.iso}-{slug} — date prefix with slug (e.g. 2025-01-15-hello-world.md), useful for Jekyll

Common patterns by use case:

• Docs and marketing pages: {title}
• Blog posts: {date.iso}-{title} or {date.iso}-{slug}
• Changelog entries: {date.iso}-{title}
• Frameworks with stricter conventions: match the filename pattern your site already expects

Field types

Fields define the frontmatter schema for a collection. Each field has a name, type, and optional validation/display options. GitCMS supports the following field types:

Title

A single-line text input optimized for entry titles. Typically used as the primary display field.

Text

A single-line text input for short text — slugs, author names, short descriptions.

Rich Text

A mini rich text editor for formatted text — descriptions, excerpts, bios. Uses a subset of the main editor's formatting capabilities.

Boolean

A toggle switch for true/false values — draft status, featured flag.

Number

A numeric input with increment/decrement controls — sort order, priority, version numbers.

Datetime

A date picker that outputs an ISO date string. Can optionally include time.

Select

A dropdown menu for choosing a single value from predefined options — category, status.

In frontmatter, the value is stored as a plain string.

Multiselect

A tag-style input for choosing multiple values — tags, categories, labels.

In frontmatter, values are stored as an array of strings:

tags:
  - javascript
  - tutorial
  - react

URL

A text input with URL validation. Use for external links, social profiles, canonical URLs.

Slug

A read-only or auto-generated slug field derived from other fields.

By default, the slug can stay in sync with the generated value as you update the fields that feed it. If you manually edit the slug, GitCMS keeps that custom value instead of forcing it to regenerate on every change.

Image

An image picker that integrates with the media library. Users can upload a new image or select an existing one.

The stored value is the file path relative to the repository root.

Common field options

Every field type accepts these shared options:

Schema inference

If you don't define a frontmatter schema for a collection, GitCMS automatically infers field types from your existing content. It analyzes the frontmatter in your Markdown files and detects:

• Common field names like title, date, description, image, tags are mapped to appropriate types.
• Values that look like dates become datetime fields.
• Values that look like URLs become url fields.
• Arrays of strings become multiselect fields.
• Boolean values become boolean fields.

This means you can start using GitCMS immediately without defining any schema — it just works with your existing content. You can then refine the schema through Settings for better labels, validation, and field-specific options.

In practice, this is useful when:

• you are bringing an existing content site into GitCMS
• your frontmatter is already consistent enough to recognize common patterns
• you want a fast first pass before fine-tuning field labels and validation

Multiple collections

Most sites have more than one type of content. Add as many collections as you need through the Settings UI. Each collection appears as a separate entry in the sidebar with its own listing page.

Common patterns:

• Blog posts — src/content/blog with title, date, tags, draft status
• Documentation — content/docs with title, order, section
• Changelog — content/changelog with title, version, date
• Team members — content/authors with name, bio, avatar, social links

Tips

• Keep field names consistent with your framework. If your Astro config expects pubDate, name the field pubDate in your frontmatter schema — not date.
• Use required sparingly. Only mark fields as required if your build will break without them. Optional fields with sensible defaults reduce friction for content creators.
• Use descriptions liberally. Brief help text prevents confusion, especially for non-technical team members.
• Start simple. You can always add more fields later. GitCMS infers schema from existing content, so you only need to define fields when you want specific types or validation.