Guides → Migrate from a custom-built site to SGEN

Migrate from a custom-built site to SGEN

Plan the move, crawl the source, map content to modules, verify the result — without losing the structure the site grew over the years.

Custom site to SGEN migration is the path for moving a site built outside a major platform — vanilla HTML/CSS/JS, a jQuery-driven site, a static-site-generator output, or an in-house CMS — into the SGEN platform. The work spans three phases: a pre-migration crawl on the source side, the content transfer itself, and a validation cycle inside SGEN before the site is treated as production-ready.

This guide walks the full arc — what to gather from the custom source, what to expect as the content lands in SGEN, where the platform model differs from a bespoke build, the eight-step sequence to run, the pitfalls to plan for, and the post-migration verification that earns the site a production-ready stamp.

What is this for?

Read this guide when you are planning a custom site to SGEN migration and want the structural picture before you commit to a date. The guide pairs the pre-migration crawl with the content-mapping procedure and the post-migration validation cycle, so the team knows what to gather, what to expect, and what to verify.

The guide covers four shapes of custom source under a single playbook because the structural moves are the same: vanilla HTML/CSS/JS sites, jQuery-driven sites, static-site-generator outputs (Jekyll, Hugo, Eleventy, Astro and similar), and in-house CMS sites where the source content lives in a custom database. The audience is the agency principal, the in-house developer scoping the move, the founder who built the site and is moving it to SGEN, or the engineer running the migration. It assumes file-system or database access on the source side and a working SGEN site to import into.

Good use cases

You are an agency migrating a client's bespoke site to SGEN and need the platform-level map.
You are an in-house team scoping the move from a custom build and want the content-mapping shape laid out before signoff.
You are a developer running the migration from a static-site generator and need the sequence, the gotchas, and the verification checklist.
You are a founder evaluating the move from a custom CMS and want the realistic timeline by site size.
You are returning to a paused migration and need the next-step anchor.

What NOT to use this for

Greenfield SGEN site build — this guide assumes a custom source exists with content to move. If the SGEN site is the first build, the onboarding documentation is the right starting point.
Per-framework porting guidance — JavaScript framework specifics (React, Vue, Angular) live in front-end development documentation. This guide is about content migration; the front-end is rebuilt inside SG-Builder.
In-place database access from SGEN — SGEN does not directly query a custom database. Content moves through structured exports or a crawled HTML capture.
Per-source bespoke export internals — site-specific export tooling is handled in internal operational documentation, not on the public guide.

How this connects to other features

Migration and Import Overview — the parent Reference area for migration discipline in SGEN, including the risk-aware framing this guide leans on.
Import — the structural model for how data lands inside SGEN after the import event.
Backups — the foundational safeguard, captured before any high-stakes operation.
Post Migration — the validation discipline that earns the migrated site its production-ready stamp.
Search and Replace — the bulk-content cleanup pass that follows a crawled-content import (URLs, asset paths, residual placeholders).
Recovery Considerations — the rollback framing if the import behaves in a way the validation cycle cannot accept.
Migrate from WordPress — sibling guide; useful framing if the custom source uses a WordPress-style template structure.

Before you start

A clean custom site to SGEN migration depends on the source side being inventoried, crawled, and content-mapped before the transfer event runs. Custom sites do not ship a standard structured export, so the migration shape leans on a site crawl paired with a content-mapping pass that defines how each source content shape lands inside a SGEN module. Gather the following before opening SGEN.

From the custom source

File-system or database access to the source site, with permission to read the content files, the asset directory, and any database that holds the dynamic content.
Page inventory — a written list of every page on the source site, with the canonical URL, the page title, the meta description, and a note on the page's primary content shape (long-form, gallery, contact, landing, blog index, blog detail, custom).
Asset inventory — a list of every file in the asset directory used by the site, including the sub-folder structure, the original filenames, and the rough size profile. Static assets, hero images, downloadable PDFs, and any other media referenced from content all land in this inventory.
Content shape inventory — for sites with a custom CMS or database, a description of every content shape (table, collection, object type) used to render the site, including the field names, the field types, and the row count per shape.
Front-end interaction inventory — a written list of every interactive surface on the source site (form, slider, accordion, tab group, custom widget). For each, note the interaction shape and the underlying behaviour. jQuery interactions, vanilla JS interactions, and custom widgets are all rebuilt inside SGEN using the equivalent first-party component or module.
Custom CSS inventory — the source stylesheets and any inline styles. SGEN's theme system covers the global palette, typography, and component-level styling; bespoke CSS that does not fit the theme system lands in Custom Codes or in per-component styling on the SGEN side.
Static asset hosting plan — for sites that load assets from a CDN or a separate static hosting surface, plan the rehost path. SGEN's media surface is the destination for migrated assets; CDN URLs that point at the source-side host need updating to the SGEN equivalent.
URL inventory and redirect plan — the full URL list from the source site, with a planned destination URL for each on the SGEN side. The list anchors the redirect map at promotion time.
Domain configuration — the canonical hostname, any subdomains, and the DNS provider currently pointing at the source site.

From the SGEN side

A live SGEN site to import into. The platform supports importing into staging first, then promoting staging to live — this is the recommended posture for any non-trivial migration.
An on-demand backup captured immediately before the transfer event. The backup is the rollback target if validation does not accept the imported state. See Backups for the safeguard discipline.
Module activation review — confirm the SGEN modules that match the content-shape inventory are enabled on the target site. Blog, Forms, Locations, Events, Custom Objects, Tracking Consent, and Custom Codes are first-party modules; activate them before the import so the imported records have a home to land in.
Theme system pre-pass — set the global palette, typography pairing, logo, and favicon on the SGEN side before the content arrives, so imported pages render against a coherent visual surface from the first preview rather than against the platform default.

Where to find it

The Import tool lives at the admin → Settings → Import. For custom-platform migrations, choose the CSV or JSON format that matches your export shape, set the field mapping on the confirmation screen, and run a staging import before promoting to live.

Steps

The full sequence is eight steps. Each is explicit about what to do, what changes, and what to verify before moving on.

1. Crawl the source site

Run a site crawl against the source URL to capture every page and its rendered HTML. The crawl is the source of truth for the migration because it captures what the source site delivers to a browser, including content rendered from any custom CMS, jQuery, or templated layer. Save the crawl output to a known location.

For static-site-generator outputs, the crawl can run against the built site rather than the source repository. The built site is what the browser sees, which is what the migration needs. For in-house CMS sites, the crawl captures the rendered output; the database remains the source-of-truth reference for content-shape inventory but does not move directly into SGEN.

2. Inventory and content-map the source

Walk the crawl output and the source-side inventory together. For every page in the crawl, decide which SGEN module is the destination. For every dynamic content shape from the custom CMS or database, decide which SGEN content surface is the destination (Custom Object, Blog, Locations, Events, or a static page).

Save the inventory and the mapping as a working document. Mark each item as "lands in module X," "rebuilt inside SGEN from inventory," "covered by Custom Codes," or "retired during migration." The four-column shape carries through the rest of the migration.

3. Build the destination shapes inside SGEN

For every custom content shape that maps to a Custom Object, open the admin → Custom Objects and create the matching object with fields that align to the source content shape. Each source field becomes a Custom Object field of the matching type. The Custom Object is the destination home for the source rows.

For every content surface that maps to a first-party module (Blog, Locations, Events, Forms), confirm the module is activated and the field set is configured to receive the imported records.

For pages that do not map to a content surface — straight static pages — note the page archetype and prepare to build the matching SG-Builder template before the import lands.

4. Prepare the asset migration

Walk the asset inventory. For each asset, plan whether the file moves to the SGEN media surface or stays on its current host with an updated reference. The default is to move the asset to the SGEN media surface so the site has a single source of truth for media. Long-tail static assets (PDFs, downloadable resources) sometimes stay on a separate host; in those cases, plan the URL rewrite in the search-and-replace step rather than the asset move.

For assets that move to the SGEN media surface, bulk-upload the asset directory through the admin → Media → Bulk Upload. The media surface preserves the file names so existing references can be rewritten path-by-path during search-and-replace.

5. Capture a backup of the SGEN target

In SGEN, open SG-Dashboard → Sites, select the target site, then trigger an on-demand backup before the content transfer begins. The backup captures the target site's current state — the rollback point if the validation cycle finds the imported state unacceptable.

Backups run as background jobs. The notification arrives when the backup file is ready. Do not start the content transfer until the backup completes. See Backups for the per-operation Reference.

6. Run the content import to a staging context

Open the admin → Migration on the target site. Select Custom source as the source. Upload the crawl archive and, for each custom content shape, the CSV or JSON export from the source database mapped to the matching Custom Object. Confirm the destination scope and start the import.

Run the import on staging first. The platform's recommended posture is import-to-staging, validate, promote-to-live. The platform records per-archive progress so a partial result is identifiable. Imported records carry identification metadata that distinguishes them from records created directly on the SGEN side. See Import for the structural model.

For pages from the crawl, the import lands the rendered content with the source HTML structure preserved. The SG-Builder rebuild step (next) reconstructs the layout against the SGEN component system.

7. Rebuild layouts inside SG-Builder, then run search-and-replace

For each page archetype identified in the inventory, build a SG-Builder template that matches the visual intent of the source. Apply the template across the imported pages of that archetype. The template-per-archetype approach is the efficient path — building each page from scratch multiplies the time without adding clarity.

For interactive surfaces (sliders, accordions, tabs, custom widgets), use the SGEN first-party components that match the interaction shape. Behaviour written as jQuery or vanilla JS on the source side does not transfer directly; the interaction is rebuilt using the component's built-in behaviour. For interactions that do not match a first-party component, Custom Codes carries the bespoke script alongside the rebuilt page.

Once layouts are rebuilt, run a Search and Replace pass to rewrite source-side URLs to the SGEN equivalents, fix asset paths to point at the SGEN media surface, and clean any residual placeholders the source HTML contained.

8. Apply redirects, then promote staging to live

Apply the redirect map from the inventory step. Every URL that lived on the source site needs a destination on the SGEN side — either the same path resolved natively, or a redirect to the new equivalent. The redirect surface inside the admin → URL Settings → Redirects carries the map.

Once validation passes, the search-and-replace pass is clean, and the redirect map is applied, promote the staging site to live through the standard staging-to-live promotion path. Update the domain DNS to point at the SGEN target. Capture a fresh backup of the live site after promotion. Run a final post-promotion validation pass — the live site sometimes behaves differently from staging because of DNS, caching, or per-environment configuration. The final pass closes the migration.

What success looks like

A successful custom site to SGEN migration ends in a verifiable state on the live site. The following observable outcomes anchor the success criteria:

Every page that existed on the source resolves on the SGEN site, either at the same path or at a documented rewrite.
Every dynamic content surface that read from the custom CMS or database renders on the SGEN side from the matching Custom Object.
Every interactive surface that ran via jQuery or vanilla JS on the source renders via the equivalent SGEN component or Custom Codes script.
Every image and asset referenced in content renders from the SGEN media surface, not from the source-side host.
Internal links resolve to the new site, not to the old one.
Site-wide settings (logo, favicon, contact information, footer text) carry the intended values.
Forms submit successfully and reach the destination configured in the Forms integration panel.

When all of the above hold, the migration is production-ready.

What to do if it does not work

Migration sometimes lands in a state the validation cycle cannot accept. The following five failure modes cover the majority of cases:

Crawl missed dynamic pages

The crawl captures pages reachable from the source-site navigation. Pages reachable only via a search, a deep link, or a sitemap entry sometimes get missed. Compare the crawl page count against the source inventory. For missing pages, extend the crawl seed list with the sitemap or the deep-link list and re-run.

Custom Object rows imported but page templates do not render them

The page template that reads the Custom Object data needs the same field names the import landed. Walk the template's data binding and confirm each field maps to the Custom Object field name. Field-name mismatches between the imported CSV and the Custom Object schema are the most common cause of empty renders.

Interactive surfaces missing on rebuilt pages

The interactive surfaces (sliders, accordions, tabs, custom widgets) are rebuilt during step seven, not auto-transferred. Walk the front-end interaction inventory from step one and complete the rebuild for any surface that is still missing.

Assets resolve through the source-side host

This is a search-and-replace miss on the media path, or an asset that did not move to the SGEN media surface. Re-run the search-and-replace pass scoped to the asset directory. For assets that have not moved across, bulk-upload them to the SGEN media surface and update the reference.

Custom CSS produces unexpected layout on imported pages

The SGEN theme system applies the global palette and typography. Custom CSS from the source side that does not fit the theme system needs scoping — typically through Custom Codes scoped per-page-class. Operators who paste source-side CSS at the site-wide scope sometimes find it interferes with imported page layouts. Scope the custom CSS narrowly and re-test.

If none of the above match the failure mode, capture the validation evidence (which pages, which behavior, what the admin event log shows), then open the Recovery Considerations Reference to plan a rollback to the backup captured in step five.

Pitfalls

Six pitfalls catch most teams running a custom site to SGEN migration for the first time. Plan for them before the transfer event runs.

Pitfall 1 — Treating the crawl as the full inventory

The site crawl captures rendered HTML. It does not capture the underlying content shape (which fields lived in which database table), the interaction behaviour (what the JS did), or the custom-CSS dependencies. The pre-migration inventory step is what closes the gap — operators who lean on the crawl alone tend to discover the missing context mid-import.

Pitfall 2 — Custom-database content imported without a destination shape

Custom CMS rows need a Custom Object on the SGEN side before they land. Operators who run the import without building the Custom Object end up with rows landing without a structured home. Build the destination shapes in step three, not at import time.

Pitfall 3 — Underestimating front-end rebuild work

jQuery interactions, custom widgets, and bespoke JS do not transfer as-is. Each interactive surface is rebuilt using the matching SGEN first-party component or via Custom Codes. The rebuild is one-per-interaction-shape rather than one-per-instance, but the inventory drives the count. Plan the rebuild as part of the migration scope, not as a post-migration follow-up.

Pitfall 4 — Asset rehost left for after promotion

Assets that stay on the source-side host after the SGEN promotion create a dependency on a system that is no longer the primary site. Plan the asset move into the SGEN media surface as part of the migration. For long-tail static assets that genuinely belong on a separate host, document the dependency explicitly so the next operator does not retire the source-side host accidentally.

Pitfall 5 — Custom CSS pasted site-wide rather than scoped

The SGEN theme system covers the global palette and typography. Source-side custom CSS that gets pasted into Custom Codes at the site-wide scope sometimes overrides theme-system values across the whole site. Scope custom CSS narrowly — per-page-class for page-specific styling, per-component for component-specific styling.

Pitfall 6 — Skipping the pre-import backup

The backup in step five is the rollback target. Operators who skip it because the import "should work" lose the rollback option when the validation cycle finds something unacceptable. Capture the backup every time — it costs minutes and protects the migration.

Gotchas — behaviour differences custom-site operators plan for

SGEN's architectural model differs from a bespoke build in ways that are not bug-shaped — the platform behaves a particular way by design. Plan for the following so the differences arrive as expected outcomes rather than surprises.

No file-system access to the rendered site

Custom-built sites usually expose a file system where pages, stylesheets, and scripts live as files. SGEN is a managed platform — pages are administered through the admin → Pages, stylesheets through the theme system, scripts through Custom Codes. The shift is from "edit a file and deploy" to "edit through the admin surface." For most operators the difference is significant on day one and recedes by week two as the admin surface becomes familiar.

Theme system covers what global stylesheets covered

A custom site usually has a primary stylesheet that defines the palette, the typography, the spacing rhythm, and the component-level styling. SGEN's theme system covers the first three at the platform level. Component-level styling is covered by SG-Builder's component traits. The migration shape is to set the theme system first (palette + typography + logo + favicon), then let component traits handle the per-component styling, with Custom Codes carrying the residual that does not fit the theme system.

Front-end interactions are first-party components

Custom sites lean on jQuery, vanilla JS, or a JavaScript framework to drive interactive surfaces. SGEN ships first-party components that match common interaction shapes — sliders, accordions, tabs, modals, forms, galleries. The migration shape is to rebuild each interactive surface using the matching component rather than carrying the bespoke script across.

For interactions that do not match a first-party component, Custom Codes carries the bespoke script alongside the rebuilt page. Scope the Custom Codes entry narrowly to the page it applies to, so site-wide behaviour stays predictable.

Custom CMS data moves through Custom Objects

In-house CMS sites usually store dynamic content in custom database tables. SGEN's Custom Objects surface is the destination. Each source table becomes a Custom Object with matching fields, each source row becomes a Custom Object record. The mapping is mechanical once the schema is captured. Page templates that read the Custom Object render the rows in the planned shape.

URL structure is set per-site, not via custom routing

Custom sites usually carry routing logic in code — a URL pattern parsed by a framework or a custom router. SGEN's URL structure is administered through the admin URL settings and applies per-site. Operators planning a redirect map define the redirects through the SGEN redirect surface rather than through a server-level rewrite file.

Backups, hosting, and security are platform-managed

Custom sites carry their own backup discipline, their own hosting setup, and their own security posture. SGEN ships backup and restore as platform capabilities, scheduled through SG-Dashboard and stored alongside the site. Hosting is the SGEN infrastructure. Security is the SGEN platform's posture. The behavioural difference is that several operational responsibilities migrate from the operator to the platform — the operator stops choosing a backup plugin, a host, and a security toolchain.

Verification — five post-migration checks

Walk these five checks after the content lands on staging, before promoting staging to live. Each is a concrete observation, not a self-report.

Check 1 — Page count and Custom Object record count match the inventory

Compare the count of imported pages inside the admin against the count from the source-side inventory. Compare each Custom Object's record count against the matching source-side row count. The numbers should match.

Check 2 — Spot-check page rendering across content types

Open one page per archetype identified in the inventory. Each should render without console errors, with media in place, with internal links resolved, and with any Custom Object data appearing where the source-side dynamic data appeared. The spot-check covers the archetypes; it is not a per-page review.

Check 3 — Interactive surfaces behave end-to-end

For each interactive surface from the inventory, walk one interaction. Submit a form. Click through a slider. Expand an accordion. Open a modal. Each interaction confirms the rebuild landed.

Check 4 — Asset references resolve through the SGEN media surface

Spot-check media references on a sample of pages. Each image, PDF, or other asset should resolve through the SGEN media surface, not through the source-side host. Asset references that still point at the source side should be added to the search-and-replace scope before promotion.

Check 5 — Redirect map covers the orphan URLs and search-engine artefacts survived

Walk a sample of the old source-side URLs and confirm each either resolves directly or redirects to the new equivalent. URLs that return a 404 response code should be added to the redirect map before promotion, not after. Confirm page titles, meta descriptions, OpenGraph tags, and structured data carry the values planned in the inventory.

When all five checks pass, the migration is verified. Promote staging to live, update the domain DNS, capture a fresh post-promotion backup, and run the validation cycle a final time on the live site to close the migration.

Examples

Example 1 — Static HTML/CSS marketing site

A founder is moving a hand-coded marketing site to SGEN. The site has 12 pages of static HTML, a stylesheet of 800 lines of CSS, no JavaScript beyond a smooth-scroll snippet, and a small set of hero and product images. The migration runs end-to-end across two to three working days. Day one is the crawl, the inventory, and the theme system pre-pass (palette + typography on the SGEN side). Day two is the import to staging, the asset bulk-upload, and the SG-Builder page rebuild against a single page template. Day three is the validation cycle, the redirect map, the staging-to-live promotion, the DNS update, and the post-promotion validation.

Example 2 — jQuery-driven multi-page site with custom CMS

An agency is moving a client site that runs 60 pages of jQuery-driven content (accordions, tabs, image galleries, an animated hero), backed by a custom PHP CMS with three content shapes (case studies, team members, press mentions). The migration runs across one to two working weeks. Days one to three are the crawl, the content-shape inventory, the Custom Object setup on the SGEN side, and the front-end interaction inventory. Days four to six are the import to staging, the asset bulk-upload, the SG-Builder template rebuild across the three page archetypes, and the interaction rebuild using SGEN first-party components. Days seven and eight are the validation cycle, the redirect map, the staging-to-live promotion, the DNS update, and the post-promotion validation.

Example 3 — Static-site-generator output with a large catalogue

A publisher is moving a content-heavy site built with a static-site generator. The source has 800 blog posts, 50 pages, an asset directory of 4,000 images, and a JSON-driven topic index. The migration runs across two to three working weeks. Week one is the crawl, the content-shape inventory, the Custom Object setup for the topic index, and the asset upload plan. Week two is the import to staging, the asset bulk-upload through the SGEN media surface, the SG-Builder template rebuild across blog and page archetypes, and the search-and-replace pass for asset references. Week three is the validation cycle, the redirect map, the staging-to-live promotion, the DNS update, and the post-promotion validation. The publisher schedules the promotion for a low-traffic window and runs the validation cycle a final time after promotion.

Recommended timeline

The timeline below covers the work end-to-end. The variability inside each bracket is real — a static-only source with a small page count lands at the lower end; a custom-CMS source with many content shapes and a heavy front-end interaction layer lands at the upper end.

Site size	Pages + content shapes	Front-end complexity	End-to-end timeline
Small	Up to ~20 pages, no custom CMS	Static or single-script	Two to three working days
Medium	20-100 pages, 1-3 custom content shapes	jQuery or moderate JS	One to two working weeks
Large	100-1,000 pages, multiple content shapes	Heavy interaction layer	Two to four working weeks
Enterprise	1,000+ pages or multilingual or multi-region	Framework-driven custom front-end	Four-plus working weeks with a planned migration window

The timeline is wall-clock time including the validation cycle and the front-end rebuild, not only the import event. The front-end rebuild, the Custom Object setup, and the asset migration account for most of the hours on a custom-source migration, since the structured-export coverage that platform-based migrations rely on is replaced by a crawl-and-map approach here.

Examples in context — how a custom-source migration earns its production stamp

Custom-source migrations earn their production stamp on the mapping discipline, not the import event. The crawl moves content cleanly; the value of the migration is in how clearly each source content shape maps to a SGEN module, how cleanly the front-end interactions are rebuilt using first-party components, and how reliably the asset references resolve through the SGEN media surface after promotion.

The discipline this guide leans on — crawl before mapping, map before importing, capture the backup before importing, run on staging before live, validate before promoting — is the same discipline the Migration and Import Overview lays out at the structural level. Following it on a custom-source migration is the difference between a migration that produces a working site on week two and a migration that produces a working site on week six after three round-trips of mapping cleanup.

Vocabulary cross-reference

Site crawl — the structured capture of every reachable page on the source site, with the rendered HTML and the asset references preserved.
Content shape — a class of content on the source side that shares a field structure (table, collection, object type). Maps to a SGEN Custom Object or first-party module.
Asset directory — the directory on the source-side host that contains images, PDFs, and other media referenced from content. Moves into the SGEN media surface.
Front-end interaction inventory — the list of every interactive surface on the source site, paired with the SGEN component or Custom Codes entry that replaces it.
Identification metadata — the trace data SGEN attaches to imported records so they are distinguishable from records created directly on the SGEN side.
Theme system pre-pass — the work of setting the palette, typography, logo, and favicon on the SGEN side before content arrives, so the first preview lands against a coherent visual surface.
Staging-first posture — the recommended discipline of importing to staging, validating, then promoting to live.
Redirect map — the table of old source-side URLs and their SGEN equivalents, applied at promotion time.

Maintenance discipline

When SGEN's migration tooling adds support for new crawl shapes, automated content-mapping helpers, or per-source-pattern importers, update this guide and log the change in Changelog. The guide stays valuable because the structural shape — crawl, map, build destination shapes, import, rebuild front-end, validate, promote — stays small. New capability lands inside that shape rather than expanding it.

When source-side patterns change (new static-site-generator output, a new in-house CMS shape, a new front-end framework in scope), revise the prerequisites and the crawl step rather than spawning a new guide. The single-guide discipline keeps the migration path findable for the operator running it.

On this page