To migrate from Contentful to genko.me, export your source data with the official CLI, then transform content models, localized fields, Rich Text, and asset references into the destination format. There is no one-step importer that reproduces a complete Contentful setup. Start with representative articles, align reference and translation IDs, and import drafts in controlled batches.
This article is written by the genko.me team. The implementation and official documentation were checked on October 20, 2026.
What should you check before leaving Contentful?
If your goal is a different editing experience or simpler operations for a small publishing site, test actual articles in both products. If your team depends on environment management, custom editor extensions, or a complex model, the cost of replacing that workflow may outweigh the benefits of moving. The official Contentful CLI documentation illustrates that environments and editor interfaces are separate migration concerns.
Inventory item | Decision to make |
|---|---|
Space and environment | Identify the exact source and distinguish production from test content |
Content types | Map each to a destination API |
Entry and asset IDs | Decide which identifiers can stay and which require translation |
Locales | Choose the main language and treatment of missing translations |
Rich Text embeds | Convert to HTML, separate fields, or frontend rendering |
Webhooks | Reconnect builds, cache invalidation, and other consumers |
Budget for transformation, frontend work, editorial review, and maintenance. Staying with Contentful is reasonable when replacing its existing workflows would add more complexity than the move removes.
1. Export Contentful with the official CLI
Use an installed and authenticated contentful-cli. The following example uses documented export options. Replace the space and environment placeholders, and keep credentials out of articles and shared repositories.
contentful space export \ --space-id SPACE_ID \ --environment-id ENVIRONMENT_ID \ --include-drafts \ --include-archived \ --download-assets \ --export-dir ./contentful-backup \ --content-file export.jsonPreserve the JSON and downloaded files. This command exports Contentful data; it does not import anything into genko.me. Repeat the export during a controlled editing freeze before cutover so that changes made since your rehearsal are not lost.
Keep the source export unchanged and generate destination files separately. That makes it possible to rerun a corrected transformation without trying to reconstruct the original data.
2. Map content types to genko.me APIs
Create the destination fields through APIs and schemas. genko.me does not automatically create APIs from Contentful content types. Start with a field mapping and review any source validation rules separately.
Source data | Possible destination | Main consideration |
|---|---|---|
Short text |
| Field IDs and required values |
Long text |
| Separate plain text from formatted article content |
Numbers, booleans, dates |
| Validate values and time zones |
Rich Text |
| Convert the JSON tree into an HTML string |
Entry links |
| Create target records and rewrite IDs |
Asset links |
| Register destination media |
Arbitrary JSON or compound data | Split fields, another API, or text storage | Do not assume a one-to-one equivalent |
Consult the field reference for actual supported types. Required fields apply to draft saves too. Decide how editors will save incomplete work and where publication-specific checks belong.
A successful import is only one part of model compatibility. Your frontend must also consume the destination values correctly, including optional fields and unresolved references.
3. Convert Contentful Rich Text to HTML
Contentful Rich Text is structured JSON. genko.me rich text is an HTML string. Passing the original document tree into a rich text field will not preserve its meaning automatically.
Contentful's official @contentful/rich-text-html-renderer exposes documentToHtmlString for basic conversion. Embedded entries and assets need resolved references and appropriate rendering rules.
Work through the following cases before accepting your conversion:
Internal entry links must resolve to the new article URLs.
Asset rendering must retain the correct file and alt text.
Embedded entries need an explicit replacement, such as a card, link, or separate field.
Tables and code must survive import, editing, and delivery.
Removing unsupported or unsafe markup must not silently remove essential information.
HTML that looks correct on a page may not remain identical after being opened and saved in a different editor. Test the full round trip: import a draft, edit it, save it, and inspect its delivered output. Make changes to the transformation before processing the rest of the collection.
4. Prepare media and referenced records
A Contentful asset ID or CDN URL does not become a genko.me image value just by copying it. There is no Contentful-specific automatic asset copier. The Newt image migration feature is a separate integration.
Register files through a content record's image or file fields, and save the record to establish media references. For a small migration, manually placing images after importing text may be practical. For a large collection, maintain a ledger with source asset ID, downloaded file, destination media ID, and articles using it.
Use a JSON export of a prepared destination article as a reference for stored values. Delivery API image values and import storage values are different, so do not use the public delivery response as an assumed import specification.
Create authors, categories, and other referenced entries before the articles that use them. If references form a cycle, initially make those references optional, create the records, and connect them through editing once the ID map exists. Reimporting the same list-format file does not update existing records.
5. Transform localized values into language-specific imports
Contentful documents field-level and entry-level localization strategies. Identify the strategy your project actually uses before deciding how to group translations.
genko.me keeps language versions under the same content ID, with values and publication status managed per language. Import the main-language records first, then match translations to those IDs. See multilingual content for configuration and delivery behavior.
This is transformed destination JSON for an API with title and body fields. It is not an unmodified Contentful export.
{ "contents": [ { "id": "article-001", "title": "Our first article", "body": "<p>HTML converted from the Rich Text document.</p>" } ]}Import main-language records as drafts.
Prepare translated field values with the same IDs.
Select the destination sub-language in the import screen.
Review matched IDs and skipped rows before importing.
Preview each language and publish only the intended versions.
A sub-language import does not create a main-language record for an unknown ID. Do not manufacture apparently translated content by copying every missing value. Leave a language version absent or choose an explicit frontend fallback policy.
By default, genko.me does not fall back to the main language. A single-entry request for a language without a published version returns 404. Make missing translations part of your frontend testing.
What does the genko.me importer not preserve?
As of October 2026, imports are limited to 10MB per file and 1,000 entries per batch. An entries array in a Contentful export does not mean its localized fields and sys structure can be imported unchanged.
Content IDs must use letters, digits, hyphens, or underscores and fit within 64 characters. Track any rewritten identifiers in your mapping table. Original publication status, schedules, creation timestamps, and revision history are not restored. Store an original publication date in a dedicated datetime field if the frontend needs it.
An existing ID stops a list import at that record. Earlier successful saves remain, so this is not an all-or-nothing operation. Reconcile saved IDs and retry only the remainder. Avoid restarting a whole batch without checking whether it would create duplicates or stop again.
Reconnect webhooks and switch the public site
The genko.me webhook sends a change notification rather than an entire article. Adapt the receiver for the new event names, signature verification, API identifiers, and language information. Automatic retries are not provided; failed deliveries can be manually resent from logs.
Manual publication uses creation or update events. Watching only entry.published would miss it. Test updates, deletion, returning a record to draft, and language-specific changes, alongside the frontend's listing, detail, preview, and cache behavior.
If URLs change, prepare individual redirects. The WordPress migration guide provides the same URL-mapping approach, while Next.js webhook revalidation addresses update propagation. Compare your media and language requirements with genko.me and its plan limits before committing to the move.
FAQ
Can I import a Contentful export directly into genko.me?
There is no complete direct migration. Transform content types, localized fields, Rich Text, references, and media to match the destination schema.
Can Contentful Rich Text be converted to HTML?
Yes. Use the official HTML renderer. Embedded entries and assets need reference resolution and rendering rules, followed by an editing round-trip check in the destination.
Can I move Contentful translations?
Yes. Transform each language and import sub-languages against matching main-language IDs. Existing localization and fallback policies are not recreated automatically.
Are Contentful webhook settings portable?
Register destination webhooks and adapt their receivers. Verify signatures, events, language handling, and failure recovery against genko.me's notification format.
Sources
Checked October 20, 2026.