juananruiz/migrate-existing-site

Migrate Existing Site

End-to-end workflow for migrating an existing website into this component starter. The goal is to reproduce the site's content and visual structure using existing components where possible, and creating new ones only when necessary.

Migration workflow overview

1. Analyze the source site — identify pages, sections, navigation, and branding
2. Set up branding — colors, fonts, and design tokens
3. Configure site data — navigation, footer, SEO
4. Map sections to existing components or flag for new creation
5. Build pages — generate pageSections YAML for each page
6. Handle images — download and place in the asset directory
7. Migrate blog — convert posts to MDX format (if applicable)

---

Step 1: Analyze the source site

Fetch and segment

Use the browser or fetch tool to load each page of the source site. For each page, identify:

• Navigation: logo, menu items, CTA buttons
• Sections: each visually distinct block on the page (separated by background changes, large spacing, or dividers)
• Footer: links, social icons, copyright text
• Brand elements: colors, fonts, logo

Per-section analysis

For each section, note:

| Observation | Record | | --------------- | ---------------------------------------------------------------- | | Layout type | Centered, split (text + image), grid of cards, accordion, slider | | Heading text | Exact text | | Body text | Exact text (preserve line breaks) | | Images | URLs, descriptions for alt text | | Buttons | Label text, link target, primary vs secondary | | Background | Light, dark, colored, image | | Repeating items | Count, fields per item (title, description, icon, image) |

---

Step 2: Set up branding

Follow the theming skill to configure the design system.

Quick checklist

1. Extract brand colors from the source site (use browser dev tools or a color picker)
2. Edit src/styles/variables/_colors.css — add brand palette values
3. Edit src/styles/themes/_light.css AND _dark.css — map brand colors to semantic tokens (always both files)
4. Edit site-fonts.mjs — set the brand's font families and weights
5. Replace public/images/logo.svg with the site's logo

---

Step 3: Configure site data

Follow the site-data-navigation skill.

Quick checklist

1. Edit src/data/seo.json — site name, URL, description, title format
2. Edit src/data/mainNav.json — logo, navigation items, CTA buttons
3. Edit src/data/footer.json — logo, links, socials, copyright text
4. Update site in astro.config.mjs to match the production URL

---

Step 4: Map sections to components

For each section identified in Step 1, match it to an existing page section or flag it for new component creation.

Section mapping table

| Source section pattern | Component to use | _component path | | -------------------------------------------------- | ------------------- | ------------------------------------------------------------------------ | | Centered hero (heading + subtext + buttons) | Hero Center | page-sections/heroes/hero-center | | Split hero (text + image side by side) | Hero Split | page-sections/heroes/hero-split | | Feature grid (grid of items with icons/titles) | Feature Grid | page-sections/features/feature-grid | | Feature showcase (text + image alternating) | Feature Split | page-sections/features/feature-split | | Feature carousel (sliding cards) | Feature Slider | page-sections/features/feature-slider | | Centered CTA (heading + buttons) | CTA Center | page-sections/ctas/cta-center | | Split CTA (text + image + buttons) | CTA Split | page-sections/ctas/cta-split | | Contact form (form + image) | CTA Form | page-sections/ctas/cta-form | | FAQ / accordion | FAQ Section | page-sections/info-blocks/faq-section | | Team members grid | Team Grid | page-sections/people/team-grid | | Testimonial / quote | Testimonial Section | page-sections/people/testimonial-section | | Custom content (doesn't fit above) | Custom Section | page-sections/builders/custom-section | | Unique layout (nothing fits) | Create new | Use screenshot-to-component skill |

Decision: reuse vs create new

Reuse an existing component when:

• The source section's layout matches an existing component's structure
• Minor visual differences can be handled by props (colorScheme, backgroundColor, reverse, alignment)
• Content fields map cleanly to the component's props

Create a new component when:

• The layout is fundamentally different from all existing components
• The section has unique interactive behavior not covered by existing wrappers
• The data shape doesn't fit any existing component's prop structure

When creating new components, use the screenshot-to-component skill if you have a visual reference, or the create-component skill for building from a description.

Using custom-section as a fallback

custom-section can compose any building blocks freely. Before creating a brand-new page section, consider whether custom-section with the right building blocks achieves the layout:

- _component: page-sections/builders/custom-section
  contentSections:
    - _component: building-blocks/core-elements/heading
      text: Section title
      level: h2
      size: lg
      alignX: center
    - _component: building-blocks/core-elements/text
      text: >-
        Body content here.
      alignX: center
    - _component: building-blocks/wrappers/grid
      minItemWidth: 300
      maxItemWidth: 400
      gap: lg
      items:
        - _component: building-blocks/wrappers/card
          border: true
          paddingHorizontal: md
          paddingVertical: md
          contentSections:
            - _component: building-blocks/core-elements/heading
              text: Card title
              level: h3
              size: sm
            - _component: building-blocks/core-elements/text
              text: Card description.
  maxContentWidth: 2xl
  paddingHorizontal: lg
  paddingVertical: 4xl
  colorScheme: inherit
  backgroundColor: surface

---

Step 5: Build pages

Create a .md file in src/content/pages/ for each page.

Content extraction rules

• Text: Copy verbatim from the source. Use >- block scalar for multiline values.
• Images: Use /src/assets/images/placeholder.jpg initially, replace after downloading (Step 6).
• Links: Map to the new site's URL structure (e.g., /about/ not https://oldsite.com/about).
• Buttons: Map to the closest variant (primary, secondary, tertiary, ghost).

Visual treatment mapping

| Source appearance | colorScheme | backgroundColor | | ------------------------------- | ------------- | ----------------------- | | White / light background | inherit | base | | Light gray background | inherit | surface | | Dark background with light text | dark | surface | | Brand-colored background | inherit | accent or highlight | | Transparent / no background | inherit | none |

Alternating sections

A common pattern is alternating backgroundColor between base and surface to visually separate sections:

pageSections:
  - _component: page-sections/heroes/hero-center
    backgroundColor: base
  - _component: page-sections/features/feature-grid
    backgroundColor: surface
  - _component: page-sections/features/feature-split
    backgroundColor: base
  - _component: page-sections/ctas/cta-center
    colorScheme: dark
    backgroundColor: surface

Feature split alternating pattern

When migrating multiple feature sections, alternate reverse to create a zigzag layout:

- _component: page-sections/features/feature-split
  reverse: false
  backgroundColor: base
- _component: page-sections/features/feature-split
  reverse: true
  backgroundColor: base
  paddingVertical: lg

Refer to the page-content-authoring skill for the full component catalog and prop reference.

---

Step 6: Handle images

Download strategy

1. Identify all images from the source site
2. Download to src/assets/images/ (Astro optimizes images from this path)
3. Organize in subdirectories if the site has many images (e.g., src/assets/images/team/, src/assets/images/blog/)
4. Update image paths in the YAML frontmatter

Image path format

Images referenced in page frontmatter use the full source path:

imageSource: /src/assets/images/hero.jpg

For static images that shouldn't be processed (like logos), place in public/images/:

logoSource: /images/logo.svg

Placeholder approach

During migration, use a placeholder first and replace later:

imageSource: /src/assets/images/placeholder.jpg
imageAlt: Descriptive alt text based on the original image

Always write meaningful alt text even when using placeholders — it won't need updating later.

---

Step 7: Migrate blog content

If the source site has a blog, follow the blog-mdx-content skill.

Quick checklist

1. Create .mdx files in src/content/blog/ for each post
2. Convert HTML content to MDX markdown
3. Set frontmatter: title, description, date, author, image, tags
4. Download and place blog images in src/assets/images/
5. Update src/content/pages/blog.md with the blog index hero section

---

Multi-page migration

When migrating multiple pages:

File structure

src/content/pages/
├── index.md          # Home page
├── about.md          # About page
├── services.md       # Services page
├── contact.md        # Contact page
├── blog.md           # Blog index (hero only; posts are in src/content/blog/)
└── search.md         # Search page (usually keep as-is)

Page priority order

1. Home page — most sections, sets the tone
2. Key landing pages — services, features, pricing
3. About / team page — uses team-grid, testimonials
4. Contact page — uses cta-form
5. Blog — last, most labor-intensive

---

Quality checklist

After migration, verify:

• [ ] All pages render without errors (npm run dev)
• [ ] Navigation links point to correct pages
• [ ] Footer links and socials are correct
• [ ] SEO data shows correct titles and descriptions
• [ ] Images load (no broken references)
• [ ] Color scheme looks correct in both light and dark sections
• [ ] Responsive layout works on mobile
• [ ] CloudCannon visual editor shows editable regions (if deployed)
• [ ] No placeholder text remains in production content