docs menu

Migrate from Contentful

The Contentful source reads the JSON file that contentful space export writes. It does not call the Contentful API: export first, then import the file.

Import#

bash
contentful space export --space-id abc123 --download-assets --export-dir ./ctf
galerne import --from contentful --file ./ctf/contentful-export-abc123-master.json --dry-run
galerne import --from contentful --file ./ctf/contentful-export-abc123-master.json

Options go after --from as flags in kebab case (projectId is --project-id). With the import_from tool, they go in options. See the migration overview for the shared flags, the report and re-runs.

OptionWhat it is
fileThe export JSON file
urlThe same file at a public URL (tools)
dataThe same JSON inline (tools)
localeThe default language. Default: the export's default locale
assetsDirectoryWhere downloaded assets are, relative to the file. Default assets, then the file's folder. Without files, assets are downloaded from their URLs

How content maps#

ContentfulGalerne
Content typeDocument type; its display field becomes the preview title
Entry idDocument id, kept
Symbol, Textstring (options from an in validation), text
Symbol named slugslug when every value is valid and unique per locale, else string
Rich TextRich text
Integer, Number, Booleannumber (integer for Integer), boolean
Datedate when every value is a plain date, else datetime
Locationgeopoint
Object (JSON)code with language json
Link to entry, array of links to entriesreference, list of references
Link to asset, array of asset linksimage or file, blocks of images or files
Array of SymbolList of strings
Localized fieldsLocalized fields
Published and changed entriesPublished version, and a draft when the entry has unpublished changes

Rich Text#

Hyperlinks become links, entry hyperlinks become doc:<id> links and asset hyperlinks media:<id> links. Embedded assets become images. Embedded entries, in blocks or inline, become embeds of an embeddedEntry block that holds a reference to the entry; an inline entry is placed after its paragraph, with a warning. Embedded resources become embeds of an embeddedResource block that keeps the URN.

What the import loses#

The report lists each of these when it happens.

  • The export holds only the latest version of an entry. An entry with changes after its last publish is imported with those changes as published, with a warning.
  • Translations are field-level only.
  • Archived entries and assets are skipped, and so are entries whose content type is missing from the export.
  • Field types not listed above are left out, with a warning. Unknown rich text marks are dropped and reported.

Export to Contentful#

bash
galerne export --to contentful --out ./ctf-export --space-id galerne
OptionWhat it is
spaceIdSpace id written in asset URLs, default galerne

The folder holds contentful-export.json with content types, entries, assets and locales, the asset files under assets/, and a README.md. Load it with contentful space import --content-file contentful-export.json --upload-assets --assets-directory assets.

The export loses:

  • One version per document: the draft is written, and the published version is left out with a warning.
  • Image alt text, hotspot and crop are not written: the field becomes a plain asset link.
  • Blocks other than images and files become separate linked entries.
  • Tables, objects and lists other than strings or references become JSON Object fields; URL, email and color fields become Symbols.
  • Code blocks become paragraphs with a code mark.
  • Embeds go back as embedded entries. An embeddedEntry links to its entry again; other blocks become entries of their own content type, and the rich text field allows those types.
  • Document-level translations get extra language and translationOf fields.
  • Ids that Contentful does not accept are rewritten with a hash.