Collections

Each collection is a distinct content structure. Creating a content document in TinaCMS is done on a per-collection basis so that:

• Content structure matches a collection definition.
• The document exists under that collection.

Each collection defines its own form fields for the TinaCMS editor.

These can be specified in the collections'fields or templates array.

The format property can be set to control the filetype of content created in the collection.

Object Definition

Must provide only one of fields or templates.

Name

name defines the name of the collection used in the GraphQL schema.

Should be unique for each collection.

We recommend using singular naming in a collection (post, not posts).

This name cannot have spaces, dashes, or special characters.

Path

path let's Tina know which directories hold documents for a collection.

Format or match properties can further specify included documents.

Documents of different collections can be co-located, but the CLI will print a warning if there are overlapping documents.

By default, the path is relative to where the CLI is running but this can be changed by using the --rootPath CLI flag.

In Local Mode, when path is changed, you will need to run tinacms dev. This ensures the generated files include the new path.

File Format

Format defines the file extension of documents in this collection. Set to one of "md", "markdown", "mdx","json", "toml", or "yaml".

If unspecified, markdown files are used.

Path Matching

match.include

A glob pattern that will be used to match a subset of the files in the path directory, not including the file extension. Use this field to exclude subdirectories or match specific filesets.

• ? matches a single character
• * matches any number of any characters (except /)
• [abc] matches any one character in the given set
• [a-z] matches a range.
• {foo,bar} matches any whole word in the given set

The final set of included files is defined from<path>/<match.include>.<format>.

To get all markdown files in the post directory (i.e.content/posts/*.md), but not subdirectories, use:

{
  path: 'content/posts',
  match: {
    include: '*',
  },
  format: 'md'
}

To get only the two files content/config/foo.json and content/config/bar.json, use:

{
  path: 'content/config',
  match: {
    include: '{foo,bar}',
  },
  format: 'json'
}

match.exclude

This works the same as match.include but will exclude any files that match the pattern. Exclude files that you don't want edited, or that are a part of a different collection.

The final set of excluded files is defined from!(<path>/<match.exclude>.<format>).

To exclude all index.md files from your collection, use:

{
  path: 'content/posts',
  match: {
    exclude: '**/index',
  },
  format: 'md'
}

Defining Defaults

The defaultItem property defines what data should exist on document creation. The default item is a function that takes in the collection and returns the default item.

All properties of the default item should correspond to fields defined on the collection.

defaultItem: () => {
  return {
    {{field name}}: {{value}}
  }
}

Default value for objects

Object field types define their default values independently. See here for more information.

Default value for rich-text

To set the default for a rich-text field, you must provide an Abstract Syntax Tree (AST). See here for more information.

Examples

Simple markdown collection

By default, files in a collection will be in markdown format.

export default defineConfig({
  //...
  schema: {
    collections: [
      {
        name: 'posts',
        label: 'Blog Posts',
        path: 'content/posts',
        fields: [
          // An array of fields
        ],
      },
    ],
  },
});

JSON collection with restricted file management permissions

The allowed actions properties control whether users can create, delete and organise content files from the collections page.

export default defineConfig({
  //...
  schema: {
    collections: [
      {
        label: 'Navigation',
        name: 'navigation',
        path: 'content/navigation',
        ui: {
          // Don't allow editors to create new navigation items
          allowedActions: {
            create: false,
            delete: false,
            createNestedFolder: false,
          },
        },
        format: 'json',
        fields: [
          // An array of fields
        ],
      },
    ],
  },
});

Markdown collection with a default title

export default defineConfig({
  // ...
  schema: {
    collections: [
      {
        label: 'Blog Posts',
        name: 'post',
        path: 'content/posts',
        defaultItem: () => {
          return {
            // When a new post is created the title field will be set to "New post"
            title: 'New Post',
          };
        },
        fields: [
          {
            type: 'string',
            label: 'Title',
            name: 'title',
          },
        ],
      },
    ],
  },
});