Here is a list of the the common things that someone may run into when migrating from Forestry to TinaCMS.

Migrating fields with non alphanumeric characters

In TinaCMS all fields can only contain alphanumeric characters or underscores. While in forestry you could have fields with non alphanumeric characters, such as my-field-name or my field name.

TinaCMS provides a nameOverride property, that allows you to specify how a field with special characters gets output.

E.g:

// collection fields
{
  name: `my_field_name`,
  nameOverride: `my-field-name`
}

The Forestry migration tool (npx @tinacms/cli init) should automatically apply nameOverride when importing your templates.

Migrating Blocks

_template vs template

The concept of using blocks as field types in forestry is supported in TinaCMS as providing templates in an object field. During the migration, the migration tool will convert your blocks into templates.

In TinaCMS, instead of the template key we use _template by default. The forestry migration tool will handle this automatically by setting the templateKey to "template" for Forestry sites, but it's something to be aware of.

Using dashes in block names

In TinaCMS, it is common for front matter templates to have - in the name. TinaCMS doesn't natively support dashes in a field name, however it does support a nameOverride property to handle this case.

For example if you had a front matter template that looked like this.

---
label: landing-page
fields:
  - type: blocks
    name: sections
    label: Sections
    template_types:
      - call-to-action
      - feature
      - hero

And content that looked like this

sections:
  - template: call-to-action
  #   ...
  - template: feature
  #   ...

Then in Tina, your block field would look like:

// ...
{
  type: "object",
  list: true,
  name: "sections",
  label: "sections",
  templateKey: 'template',
  templates: [
    {
      name: 'call-to-action',
      nameOverride: 'call_to_action',
      fields: [
        //...
      ]
    },
    // ...
  ]
}

Your output content would continue to look like:

- template: call-to-action
#   ...
# this assumes your block has templateKey: 'template' set on your blocks field.
- template: feature
#   ...

Common error message and how to fix them

Error: Block template "TemplateName" is not defined for field "FieldName"

In forestry you could have a block field that had a template that was not defined in the front matter template. In TinaCMS, this is not allowed. You will have to add the template from forestry to to the list of templates in the blocks field and define the fields for that template.

See a more in depth video explaining here

Error when getting content in the admin

[Error] GetCollection failed: Unable to fetch, errors: Error querying file <File> from collection pages. Please run "tinacms audit" or add the --verbose option for more info

This can happen for many reasons. Some common reasons are because the data you are trying to fetch is

• not in the correct format
• missing a required field
• is missing the _template key. If you look at the error message in the terminal you should see the exact error that is causing the issue.

For example, if you are missing _template you will see an error like this

Error: Unable to determine template for item at hugo/content/about.md, no template name provided for collection with multiple templates
    at TinaSchema.getCollectionAndTemplateByFullPath (/Users/logananderson-forestry-mac/dev/forestry.io/forestry.io/node_modules/@tinacms/schema-tools/dist/index.js:224:19)

This can be fixed by adding the _template key to the front matter of the file.

---
# ...
_template: my_template
---

..where "my_template" is the name of the template in the collection to which the file belongs.

Error YAMLException: duplicated mapping key

This happens when you have two keys in the frontmatter of your markdown files that are the same. In forestry, this was allowed but in TinaCMS it is not. You will have to remove one of the keys.

For example, if you have a file that looks like this

---
date: 2021-01-01
date: 2021-01-02
---

It will have to be changed to

---
date: 2021-01-02
---

Info: Match was transformed to newMatch

The match property works a bit differently in TinaCMS than it does in Forestry. In Forestry, the match property is a glob pattern that includes the file extension. In TinaCMS, the match property is a glob pattern that does not include the file extension.

In TinaCMS the match property is set for each collection and is nested.

{
  label: 'Pages',
  name: 'pages',
  match: {
    include: "{foo,ba}/**/*"
  }
  //..
}

Check out the match property docs for more info.

Since this migration tool is converting from Forestry to TinaCMS, it will automatically convert the match property to the TinaCMS format. It is a good idea to double check that it is matching correctly.

Last Edited: August 30, 2024