markusgraf_ch/openspec/specs/content-migration/spec.md

# content-migration Specification

## Purpose
TBD - created by archiving change migrate-site-content. Update Purpose after archive.
## Requirements
### Requirement: Content Extraction from Live Site
The system SHALL capture all text content, structure, and formatting from the live markusgraf.ch website to migrate into the Hugo project.

#### Scenario: Extract homepage content from live site
- **GIVEN** the live markusgraf.ch website HTML source is provided
- **WHEN** the HTML is parsed for content extraction
- **THEN** all text content, headings, and structure are captured
- **AND** the content is organized by logical sections (bio, intro, projects, etc.)

#### Scenario: Extract projects and portfolio content
- **GIVEN** the live site contains project or portfolio information
- **WHEN** projects are identified and extracted
- **THEN** each project has complete description captured
- **AND** project metadata and structure is documented

### Requirement: Content Conversion to Hugo Format
The system SHALL convert extracted HTML content into Hugo-compatible markdown format while preserving formatting and structure.

#### Scenario: Convert HTML to markdown
- **GIVEN** extracted HTML content from live site
- **WHEN** content is converted to markdown
- **THEN** all text formatting is preserved (bold, italic, links)
- **AND** HTML-specific elements are converted to markdown or Hugo shortcodes
- **AND** content follows markdown best practices

#### Scenario: Add Hugo front matter
- **GIVEN** converted markdown content
- **WHEN** content files are created
- **THEN** appropriate YAML front matter is added (title, description, date)
- **AND** front matter variables are correctly configured for templates

### Requirement: Homepage Content Integration
The system SHALL integrate migrated homepage content into content/_index.md, replacing placeholder content.

#### Scenario: Update homepage with actual content
- **GIVEN** converted homepage markdown content
- **WHEN** content/_index.md is updated
- **THEN** all placeholder text is replaced with actual content
- **AND** all sections from live site are present
- **AND** content hierarchy and flow matches live site structure

#### Scenario: Image references in content
- **GIVEN** homepage content references images
- **WHEN** image references are added to markdown
- **THEN** images use Hugo static path conventions (e.g., /images/photo.jpg)
- **AND** all image markdown syntax is correct

### Requirement: Content Structure Parity
The system SHALL ensure the Hugo site content structure matches the live markusgraf.ch site organization.

#### Scenario: Section organization matches live site
- **GIVEN** live site has distinct sections
- **WHEN** content is organized in Hugo
- **THEN** all sections are represented
- **AND** section order matches live site
- **AND** navigation between sections works correctly

#### Scenario: Multi-page structure if needed
- **GIVEN** live site has multiple pages
- **WHEN** pages are created in Hugo
- **THEN** each page has corresponding content file
- **AND** internal links between pages work
- **AND** navigation reflects page structure

### Requirement: Content Verification
The system SHALL verify that migrated content achieves parity with the live site.

#### Scenario: Content completeness check
- **GIVEN** Hugo site is built with migrated content
- **WHEN** compared with live markusgraf.ch
- **THEN** all text content from live site is present
- **AND** no content is missing or truncated
- **AND** content meaning and context are preserved

#### Scenario: Visual structure comparison
- **GIVEN** Hugo site is rendered
- **WHEN** viewed alongside live site
- **THEN** content sections appear in same order
- **AND** heading hierarchy matches
- **AND** overall content flow is equivalent