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#
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.jsonOptions 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.
| Option | What it is |
|---|---|
file | The export JSON file |
url | The same file at a public URL (tools) |
data | The same JSON inline (tools) |
locale | The default language. Default: the export's default locale |
assetsDirectory | Where 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#
| Contentful | Galerne |
|---|---|
| Content type | Document type; its display field becomes the preview title |
| Entry id | Document id, kept |
| Symbol, Text | string (options from an in validation), text |
Symbol named slug | slug when every value is valid and unique per locale, else string |
| Rich Text | Rich text |
| Integer, Number, Boolean | number (integer for Integer), boolean |
| Date | date when every value is a plain date, else datetime |
| Location | geopoint |
| Object (JSON) | code with language json |
| Link to entry, array of links to entries | reference, list of references |
| Link to asset, array of asset links | image or file, blocks of images or files |
| Array of Symbol | List of strings |
| Localized fields | Localized fields |
| Published and changed entries | Published 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#
galerne export --to contentful --out ./ctf-export --space-id galerne| Option | What it is |
|---|---|
spaceId | Space 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
Objectfields; URL, email and color fields become Symbols. - Code blocks become paragraphs with a code mark.
- Embeds go back as embedded entries. An
embeddedEntrylinks 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
languageandtranslationOffields. - Ids that Contentful does not accept are rewritten with a hash.